Realms

Realms are rooted in /v1/realms collection.

Each realm defines a specific authentication provider. Any of the authentication providers can be used to obtain access tokens that can be used with Nexus.

Authorization notes

When modifying realms, the caller must have realms/write permissions on the path /.

When reading realms, the caller must have realms/read permissions on the path /.

Please visit Authentication & authorization section to learn more about it.

Payload

{
  "name": "{name}",
  "openIdConfig": "{openIdConfig}",
  "logo": "{logo}",
  "acceptedAudiences": {acceptedAudiences}
}

where…

  • {name}: String - the realm name.
  • {openIdConfig}: IRI - the provider OpenID configuration.
  • {logo}: IRI - the logo Url for the realm. This field is optional.
  • {acceptedAudiences}: Array[String] - ar array of accepted audiences as string values. If provided, the token should have the aud with some of its values matching some of the acceptedAudience values on the realm. This field is optional.

Create

This operation creates a realm.

PUT /v1/realms/{realm}

The following examples describe the payload used to create a realm.

Example

Request
sourcecurl -XPUT \
  -H "Content-Type: application/json" \
  "http://localhost:8080/v1/realms/realm1" \
  -d '{
        "name":"Nexus Dev",
        "openIdConfig":"http://localhost:8080/auth/realms/bbp-test/.well-known/openid-configuration",
        "logo":"http://localhost:8080/logo.png"
      }'
Payload
source{
  "name": "Nexus Dev",
  "openIdConfig": "http://localhost:8080/auth/realms/bbp-test/.well-known/openid-configuration",
  "logo": "http://localhost:8080/logo.png"
}
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/realms-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/realms/realm1",
  "@type": "Realm",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/realms.json",
  "_createdAt": "2021-05-11T09:42:41.313Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_label": "realm1",
  "_rev": 1,
  "_self": "http://localhost:8080/v1/realms/realm1",
  "_updatedAt": "2021-05-11T09:42:41.313Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous"
}

Update

This operation updates a realm.

PUT /v1/realms/{realm}?rev={previous_rev}
  {...}

where {previous_rev} is the last known revision number for the realm. The json payload should be the same as the one used to create realms.

Example

Request
sourcecurl -XPUT \
  -H "Content-Type: application/json" \
  "http://localhost:8080/v1/realms/realm1?rev=1" \
  -d '{
        "name":"Nexus Dev",
        "openIdConfig":"http://localhost:8080/auth/realms/bbp-test/.well-known/openid-configuration",
        "logo":"http://localhost:8080/logo.png"
      }'
Payload
source{
  "name": "Nexus Dev",
  "openIdConfig": "http://localhost:8080/auth/realms/bbp-test/.well-known/openid-configuration",
  "logo": "http://localhost:8080/logo.png"
}
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/realms-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/realms/realm1",
  "@type": "Realm",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/realms.json",
  "_createdAt": "2021-05-11T09:42:41.313Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_label": "realm1",
  "_rev": 2,
  "_self": "http://localhost:8080/v1/realms/realm1",
  "_updatedAt": "2021-05-11T09:45:20.409Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous"
}

Deprecate

This operation deprecates a realm.

DELETE /v1/realms/{realm}?rev={previous_rev}

where {previous_rev} is the last known revision number for the realm.

Request
sourcecurl -XDELETE  "http://localhost:8080/v1/realms/realm1?rev=2"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/realms-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/realms/realm1",
  "@type": "Realm",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/realms.json",
  "_createdAt": "2021-05-11T09:42:41.313Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": true,
  "_label": "realm1",
  "_rev": 3,
  "_self": "http://localhost:8080/v1/realms/realm1",
  "_updatedAt": "2021-05-11T09:48:57.296Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous"
}

List

Lists all available realms.

 GET /v1/realms?from={from}
                 &size={size}
                 &deprecated={deprecated}
                 &rev={rev}
                 &createdBy={createdBy}
                 &updatedBy={updatedBy}
                 &sort={sort}

where…

  • {from}: Number - the offset from which to start the listings. Defaults to 0
  • {size}: Number - the maximum amount fo results to be returned. Defaults to 30
  • {deprecated}: Boolean - filter the resulting realms based on their deprecation status. Optional parameter.
  • {rev}: Number - filter the resulting realms based on their revision value. Optional parameter.
  • {createdBy}: Iri - filter the resulting realms based on their creator. Optional parameter.
  • {updatedBy}: Iri - filter the resulting realms based on the person which performed the last update. Optional parameter.
  • {sort}: String - orders the resulting realms based on its metadata fields. Optional parameter that can appear multiple times, further specifying the ordering criteria. Defaults to _createdAt, ordering realms by creation date.
Request
sourcecurl "http://localhost:8080/v1/realms"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/metadata.json",
    "https://bluebrain.github.io/nexus/contexts/search.json",
    "https://bluebrain.github.io/nexus/contexts/realms.json"
  ],
  "_total": 1,
  "_results": [
    {
      "@id": "http://localhost:8080/v1/realms/realm1",
      "@type": "Realm",
      "logo": "http://localhost:8080/logo.png",
      "name": "BlueBrain",
      "openIdConfig": "http://localhost:8080/auth/realms/realm1/.well-known/openid-configuration",
      "_authorizationEndpoint": "http://localhost:8080/auth/realms/realm1/protocol/openid-connect/auth",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/realms.json",
      "_createdAt": "2021-05-11T09:42:41.313Z",
      "_createdBy": "http://localhost:8080/v1/anonymous",
      "_deprecated": true,
      "_endSessionEndpoint": "http://localhost:8080/auth/realms/realm1/protocol/openid-connect/logout",
      "_grantTypes": [
        "password",
        "clientCredentials",
        "refreshToken",
        "authorizationCode",
        "implicit"
      ],
      "_issuer": "http://localhost:8080/auth/realms/realm1",
      "_label": "realm1",
      "_rev": 3,
      "_self": "http://localhost:8080/v1/realms/realm1",
      "_tokenEndpoint": "http://localhost:8080/auth/realms/realm1/protocol/openid-connect/token",
      "_updatedAt": "2021-05-11T09:48:57.296Z",
      "_updatedBy": "http://localhost:8080/v1/anonymous",
      "_userInfoEndpoint": "http://localhost:8080/auth/realms/realm1/protocol/openid-connect/userinfo"
    }
  ]
}

Fetch (current version)

GET /v1/realms/{realm}

Example

Request
sourcecurl "http://localhost:8080/v1/realms/realm1"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/realms.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/realms/realm1",
  "@type": "Realm",
  "logo": "http://localhost:8080/logo.png",
  "name": "BlueBrain",
  "openIdConfig": "http://localhost:8080/auth/realms/BBP/.well-known/openid-configuration",
  "_authorizationEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/auth",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/realms.json",
  "_createdAt": "2021-05-11T09:42:41.313Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": true,
  "_endSessionEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/logout",
  "_grantTypes": [
    "password",
    "clientCredentials",
    "refreshToken",
    "authorizationCode",
    "implicit"
  ],
  "_issuer": "http://localhost:8080/auth/realms/BBP",
  "_label": "realm1",
  "_rev": 3,
  "_self": "http://localhost:8080/v1/realms/realm1",
  "_tokenEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/token",
  "_updatedAt": "2021-05-11T09:48:57.296Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_userInfoEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/userinfo"
}

Fetch (specific version)

GET /v1/realms/{realm}?rev={rev}

… where {rev} is the revision number of the resolver to be retrieved.

Example

Request
sourcecurl "http://localhost:8080/v1/realms/realm1?rev=1"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/realms.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/realms/realm1",
  "@type": "Realm",
  "logo": "http://localhost:8080/logo.png",
  "name": "BlueBrain",
  "openIdConfig": "http://localhost:8080/auth/realms/BBP/.well-known/openid-configuration",
  "_authorizationEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/auth",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/realms.json",
  "_createdAt": "2021-05-11T09:42:41.313Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": true,
  "_endSessionEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/logout",
  "_grantTypes": [
    "password",
    "clientCredentials",
    "refreshToken",
    "authorizationCode",
    "implicit"
  ],
  "_issuer": "http://localhost:8080/auth/realms/BBP",
  "_label": "realm1",
  "_rev": 3,
  "_self": "http://localhost:8080/v1/realms/realm1",
  "_tokenEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/token",
  "_updatedAt": "2021-05-11T09:48:57.296Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_userInfoEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/userinfo"
}
v1.11.x