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"}'
Full source at GitHub
Payload
{
  "name": "Nexus Dev",
  "openIdConfig": "https://nexus.example.com/auth/realms/bbp-test/.well-known/openid-configuration",
  "logo": "http://nexus.example.com/logo.png"
}
Full source at GitHub
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"
}
Full source at GitHub

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"}'
Full source at GitHub
Payload
{
  "name": "Nexus Dev",
  "openIdConfig": "https://nexus.example.com/auth/realms/bbp-test/.well-known/openid-configuration",
  "logo": "http://nexus.example.com/logo.png"
}
Full source at GitHub
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"
}
Full source at GitHub

Delete a realm

This operation deletes a realm.

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"
Full source at GitHub
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"
}
Full source at GitHub

List realms

Lists all available realms.

 GET /v1/realms
Request
curl "https://nexus.example.com/v1/realms"
Full source at GitHub
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"
    }
  ]
}
Full source at GitHub

Fetch a realm (current version)

GET /v1/realms/{realm}

Example

Request
curl "https://nexus.example.com/v1/realms/realm1"
Full source at GitHub
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"
}
Full source at GitHub

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"
Full source at GitHub
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"
}
Full source at GitHub