Outdated version

You are browsing the docs for Nexus v1.6.x, the latest release is available here

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"
}

Server Sent Events

This endpoint allows clients to receive automatic updates from the realms in a streaming fashion.

GET /v1/realms/events

where Last-Event-Id is an optional HTTP Header that identifies the last consumed realm event. It can be used for cases when a client does not want to retrieve the whole event stream, but to start after a specific event.

The response contains a series of realm events, represented in the following way

data:{payload}
event:{type}
id:{id}

where…

  • {payload}: Json - is the actual payload of the current realm
  • {type}: String - is a type identifier for the current realm. Possible types are: RealmCreated, RealmUpdated and RealmDeprecated
  • {id}: String - is the identifier of the realm event. It can be used in the Last-Event-Id HTTP Header

Example

Request
sourcecurl "http://localhost:8080/v1/realms/events"
Response
sourcedata:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/realms.json"],"@type":"RealmCreated","name":"BlueBrain","openIdConfig":"http://localhost:8080/auth/realms/realm1/.well-known/openid-configuration","_authorizationEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/auth","_endSessionEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/logout","_grantTypes":["password","clientCredentials","refreshToken","authorizationCode","implicit"],"_instant":"2021-05-11T09:42:41.313Z","_issuer":"http://localhost:8080/auth/realms/realm1","_label":"realm1","_realmId":"http://localhost:8080/v1/realms/realm1","_rev":1,"_subject":"http://localhost:8080/v1/anonymous","_tokenEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/token","_userInfoEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/userinfo"}
event:RealmCreated
id:3abfce50-b23d-11eb-bef4-251deaef3e83

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/realms.json"],"@type":"RealmUpdated","logo":"http://google.com","name":"BlueBrain","openIdConfig":"http://localhost:8080/auth/realms/realm1/.well-known/openid-configuration","_authorizationEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/auth","_endSessionEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/logout","_grantTypes":["password","clientCredentials","refreshToken","authorizationCode","implicit"],"_instant":"2021-05-11T09:45:20.409Z","_issuer":"http://localhost:8080/auth/realms/realm1","_label":"realm1","_realmId":"http://localhost:8080/v1/realms/realm1","_rev":2,"_subject":"http://localhost:8080/v1/anonymous","_tokenEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/token","_userInfoEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/userinfo"}
event:RealmUpdated
id:999107a0-b23d-11eb-bef4-251deaef3e83

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/realms.json"],"@type":"RealmDeprecated","_instant":"2021-05-11T09:48:57.296Z","_label":"realm1","_realmId":"http://localhost:8080/v1/realms/realm1","_rev":3,"_subject":"http://localhost:8080/v1/anonymous"}
event:RealmDeprecated
id:1ad75c10-b23e-11eb-bef4-251deaef3e83
v1.6.x