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