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.

Access to resources in the system depends on the access control list set for them. Depending on the access control list, a caller may need to prove its identity by means of an access token passed to the Authorization header (Authorization: Bearer {token}). Please visit Authentication to learn more about how to retrieve an access token.

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 /.

Create a realm

This operation creates a realm.

PUT /v1/realms/{realm}

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

Example

Request

curl -XPUT -H "Content-Type: application/json" "https://nexus.example.com/v1/realms/realm1" \
    -d '{"name":"Nexus Dev","openIdConfig":"https://nexus.example.com/auth/realms/bbp-test/.well-known/openid-configuration","logo":"http://nexus.example.com/logo.png"}'

Payload

{
  "name": "Nexus Dev",
  "openIdConfig": "https://nexus.example.com/auth/realms/bbp-test/.well-known/openid-configuration",
  "logo": "http://nexus.example.com/logo.png"
}

Response

{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/iam.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/v1/realms/realm1",
  "@type": "Realm",
  "_label": "realm1",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2018-09-18T09:58:00.801Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-18T09:58:00.801Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

The logo parameter is optional.

Update a realm

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

curl -XPUT -H "Content-Type: application/json" "https://nexus.example.com/v1/realms/realm1?rev=1" \
    -d '{"name":"Nexus Dev","openIdConfig":"https://nexus.example.com/auth/realms/bbp-test/.well-known/openid-configuration","logo":"http://nexus.example.com/logo.png"}'

Payload

{
  "name": "Nexus Dev",
  "openIdConfig": "https://nexus.example.com/auth/realms/bbp-test/.well-known/openid-configuration",
  "logo": "http://nexus.example.com/logo.png"
}

Response

{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/iam.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/v1/realms/realm1",
  "@type": "Realm",
  "_label": "realm1",
  "_rev": 2,
  "_deprecated": false,
  "_createdAt": "2018-09-18T09:58:00.801Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-18T10:25:00.801Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

Deprecate a realm

This operation deprecates a realm. After deprecation, realms loose their metadata

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

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

Request

curl -XDELETE  -H "Content-Type: application/json" "https://nexus.example.com/v1/realms/realm1?rev=2"

Response

{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/iam.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/v1/realms/realm1",
  "@type": "Realm",
  "_label": "realm1",
  "_rev": 3,
  "_deprecated": true,
  "_createdAt": "2018-09-18T09:58:00.801Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-18T10:25:00.801Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

List realms

Lists all available realms.

 GET /v1/realms?deprecated={deprecated}&rev={rev}&type={type}&createdBy={createdBy}&updatedBy={updatedBy}

where…

{deprecated}: Boolean - can be used to filter the resulting realms based on their deprecation status
{rev}: Number - can be used to filter the resulting realms based on their revision value
{type}: Iri - can be used to filter the resulting realms based on their @type value. This parameter can appear multiple times, filtering further the @type value.
{createdBy}: Iri - can be used to filter the resulting realms based on their creator
{updatedBy}: Iri - can be used to filter the resulting realms based on the person which performed the last update

Request

curl "https://nexus.example.com/v1/realms"

Response

{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/resource.json",
    "https://bluebrain.github.io/nexus/contexts/iam.json",
    "https://bluebrain.github.io/nexus/contexts/search.json"
  ],
  "_total": 2,
  "_results": [
    {
      "@id": "http://nexus.example.com/v1/realms/realm1",
      "@type": "Realm",
      "name": "Github Dev",
      "openIdConfig": "http://nexus.example.com/auth/realms/realm1/.well-known/openid-configuration",
      "_label": "realm1",
      "_grantTypes": [
        "password",
        "clientCredentials",
        "refreshToken",
        "authorizationCode",
        "implicit"
      ],
      "_issuer": "http://nexus.example.com/auth/realms/realm1",
      "_authorizationEndpoint": "http://nexus.example.com/auth/realms/realm1/protocol/openid-connect/auth",
      "_tokenEndpoint": "http://nexus.example.com/auth/realms/realm1/protocol/openid-connect/token",
      "_userInfoEndpoint": "http://nexus.example.com/auth/realms/realm1/protocol/openid-connect/userinfo",
      "_endSessionEndpoint": "http://nexus.example.com/auth/realms/realm1/protocol/openid-connect/logout",
      "_rev": 3,
      "_deprecated": false,
      "_createdAt": "2019-01-22T10:50:47.351Z",
      "_createdBy": "http://nexus.example.com/v1/anonymous",
      "_updatedAt": "2019-01-22T12:24:13.029Z",
      "_updatedBy": "http://nexus.example.com/v1/anonymous"
    },
    {
      "@id": "http://nexus.example.com/v1/realms/realm2",
      "@type": "Realm",
      "name": "Realm 2",
      "openIdConfig": "http://nexus.example.com/auth/realms/realm2/.well-known/openid-configuration",
      "_label": "realm2",
      "_grantTypes": [
        "password",
        "clientCredentials",
        "refreshToken",
        "authorizationCode",
        "implicit"
      ],
      "_issuer": "http://nexus.example.com/auth/realms/realm2",
      "_authorizationEndpoint": "http://nexus.example.com/auth/realms/realm2/protocol/openid-connect/auth",
      "_tokenEndpoint": "http://nexus.example.com/auth/realms/realm2/protocol/openid-connect/token",
      "_userInfoEndpoint": "http://nexus.example.com/auth/realms/realm2/protocol/openid-connect/userinfo",
      "_endSessionEndpoint": "http://nexus.example.com/auth/realms/realm2/protocol/openid-connect/logout",
      "_rev": 1,
      "_deprecated": false,
      "_createdAt": "2019-01-22T12:22:50.738Z",
      "_createdBy": "http://nexus.example.com/v1/anonymous",
      "_updatedAt": "2019-01-22T12:22:50.738Z",
      "_updatedBy": "http://nexus.example.com/v1/anonymous"
    }
  ]
}

Fetch a realm (current version)

GET /v1/realms/{realm}

Example

Request

curl "https://nexus.example.com/v1/realms/realm1"

Response

{
  "@id": "http://nexus.example.com/v1/realms/realm1",
  "@type": "Realm",
  "name": "Github Dev",
  "openIdConfig": "http://nexus.example.com/auth/realms/realm1/.well-known/openid-configuration",
  "_label": "realm1",
  "_grantTypes": [
    "password",
    "clientCredentials",
    "refreshToken",
    "authorizationCode",
    "implicit"
  ],
  "_issuer": "http://nexus.example.com/auth/realms/realm1",
  "_authorizationEndpoint": "http://nexus.example.com/auth/realms/realm1/protocol/openid-connect/auth",
  "_tokenEndpoint": "http://nexus.example.com/auth/realms/realm1/protocol/openid-connect/token",
  "_userInfoEndpoint": "http://nexus.example.com/auth/realms/realm1/protocol/openid-connect/userinfo",
  "_endSessionEndpoint": "http://nexus.example.com/auth/realms/realm1/protocol/openid-connect/logout",
  "_rev": 3,
  "_deprecated": false,
  "_createdAt": "2019-01-22T10:50:47.351Z",
  "_createdBy": "http://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-22T12:24:13.029Z",
  "_updatedBy": "http://nexus.example.com/v1/anonymous"
}

Fetch a realm (specific version)

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

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

Example

Request

curl "https://nexus.example.com/v1/realms/realm1?rev=3"

Response

{
  "@id": "http://nexus.example.com/v1/realms/realm1",
  "@type": "Realm",
  "name": "Github Dev",
  "openIdConfig": "http://nexus.example.com/auth/realms/realm1/.well-known/openid-configuration",
  "_label": "realm1",
  "_grantTypes": [
    "password",
    "clientCredentials",
    "refreshToken",
    "authorizationCode",
    "implicit"
  ],
  "_issuer": "http://nexus.example.com/auth/realms/realm1",
  "_authorizationEndpoint": "http://nexus.example.com/auth/realms/realm1/protocol/openid-connect/auth",
  "_tokenEndpoint": "http://nexus.example.com/auth/realms/realm1/protocol/openid-connect/token",
  "_userInfoEndpoint": "http://nexus.example.com/auth/realms/realm1/protocol/openid-connect/userinfo",
  "_endSessionEndpoint": "http://nexus.example.com/auth/realms/realm1/protocol/openid-connect/logout",
  "_rev": 3,
  "_deprecated": false,
  "_createdAt": "2019-01-22T10:50:47.351Z",
  "_createdBy": "http://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-22T12:24:13.029Z",
  "_updatedBy": "http://nexus.example.com/v1/anonymous"
}

Realms 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

curl "https://nexus.example.com/v1/realms/events"

Response

data:{"@context":["https://bluebrain.github.io/nexus/contexts/iam.json","https://bluebrain.github.io/nexus/contexts/resource.json"],"@id":"http://nexus.example.com/v1/realms/github","@type":"RealmCreated","name":"Github","openIdConfig":"https://nexus.example.com/nexus/auth/realms/github-dev/.well-known/openid-configuration","_label":"github","_grantTypes":["password","clientCredentials","refreshToken","authorizationCode","implicit"],"_issuer":"https://nexus.example.com/nexus/auth/realms/github-dev","_keys":[{"alg":"RS256","e":"AQAB","kid":"*****","kty":"RSA","n":"***","use":"sig"}],"_authorizationEndpoint":"https://nexus.example.com/nexus/auth/realms/github-dev/protocol/openid-connect/auth","_tokenEndpoint":"https://nexus.example.com/nexus/auth/realms/github-dev/protocol/openid-connect/token","_userInfoEndpoint":"https://nexus.example.com/nexus/auth/realms/github-dev/protocol/openid-connect/userinfo","_endSessionEndpoint":"https://nexus.example.com/nexus/auth/realms/github-dev/protocol/openid-connect/logout","_rev":1,"_instant":"2019-06-11T11:31:52.278Z","_subject":"http://nexus.example.com/v1/anonymous"}
event:RealmCreated
id:83bf27a2-8c3c-11e9-a8f6-c5c16f2312d6

data:{"@context":["https://bluebrain.github.io/nexus/contexts/iam.json","https://bluebrain.github.io/nexus/contexts/resource.json"],"@id":"http://nexus.example.com/v1/realms/github","@type":"RealmUpdated","logo":"http://nexus.example.com/logo.png","name":"Github""openIdConfig":"https://nexus.example.com/nexus/auth/realms/github-dev/.well-known/openid-configuration","_label":"github","_grantTypes":["password","clientCredentials","refreshToken","authorizationCode","implicit"],"_issuer":"https://nexus.example.com/nexus/auth/realms/github-dev","_keys":[{"alg":"RS256","e":"AQAB","kid":"*****","kty":"RSA","n":"***","use":"sig"}],"_authorizationEndpoint":"https://nexus.example.com/nexus/auth/realms/github-dev/protocol/openid-connect/auth","_tokenEndpoint":"https://nexus.example.com/nexus/auth/realms/github-dev/protocol/openid-connect/token","_userInfoEndpoint":"https://nexus.example.com/nexus/auth/realms/github-dev/protocol/openid-connect/userinfo","_endSessionEndpoint":"https://nexus.example.com/nexus/auth/realms/github-dev/protocol/openid-connect/logout","_rev":2,"_instant":"2019-06-14T11:56:58.372Z","_subject":"http://nexus.example.com/v1/realms/nexusdev/users/anonymous"}
event:RealmUpdated
id:835128c0-8e9b-11e9-a8f6-c5c16f2312d6

data:{"@context":["https://bluebrain.github.io/nexus/contexts/iam.json","https://bluebrain.github.io/nexus/contexts/resource.json"],"@id":"http://nexus.example.com/v1/realms/github","@type":"RealmDeprecated","_label":"internal","_rev":3,"_instant":"2019-06-14T11:57:01.426Z","_subject":"http://nexus.example.com/v1/realms/nexusdev/users/myuser"}
event:RealmDeprecated
id:85054160-8e9b-11e9-a8f6-c5c16f2312d6

Edit this page

2116264d