There are two GraphQL APIs in the server. One is a sub-endpoint of the Dynamic Client Registration endpoint to work with DCR clients. The other is the User Management GraphQL endpoint. It contains a schema to manage user accounts as graph data.
In order to work with the GraphQL API an access token needs to be obtained. The authorization manager configured on the corresponding profile defines what the token needs to contain in order to gain access.
Most commonly it needs to contain a certain scope to pass the first authorization step, and if the groups authorization manager is used it also needs to contain the groups claim with a user group that matches one of the rules in the authorization manager.
The GraphQL schema can be obtained from the GraphQL endpoint. However it is required to provide an access token with at least read access to see the schema.
Most GraphQL tools allow you to configure the headers sent when accessing the endpoints.
Fig. 188 Example of adding an access token to GraphiQL
After this is done, the tool will be able to introspect the endpoint and the schema should become visible.
The schema exposes two top level types: Query and Mutation. The Query is used when reading data and Mutation when updating.
Query
Mutation
Fig. 189 Top level schema in GraphiQL
Fig. 190 Query schema in GraphiQL
There are two types of queries, singular and plural; to obtain a single account or multiple.
query SingleAccount { accountByUserName(userName: "johndoe") { id userName emails { primary value } } }
{ "data": { "accountByUserName": { "id": "b626d5d206f64165bb5c14a843545c9d", "userName": "johndoe", "emails": [ { "primary": true, "value": "john.doe@example.com" } ] } } }
When reading multiple accounts the system provides cursor based pagination to be able to get partial results. It’s also possible to filter the result.
query AllAccounts{ accounts(sorting: { sortBy: created, sortOrder: ASCENDING } ) { edges { node { id userName emails { value primary } } } pageInfo { endCursor hasNextPage } totalCount } }
{ "data": { "accounts": { "edges": [ { "node": { "id": "1e99fb8210a944f1b6069a0cfe1c59c5", "userName": "bcryptUser", "emails": [ { "value": "bcrypt.user@example.com", "primary": true } ] } }, ] "pageInfo": { "endCursor": null, "hasNextPage": false }, "totalCount": 13
The API loosely follows the definitions in relay.dev for pagination. Most concepts in the GraphQL APIs should be familiar to anyone experienced with GraphQL APIs.
When a GraphQL mutation fails due to data source constraints violation, a GraphQL error message is returned. The errors.extensions.field element contains the details about the attribute causing the violation.
errors.extensions.field
userName
{ "errors": [ { "message": "The username provided is already registered", "locations": [], "extensions": { "classification": "constraint-violation", "field": "userName" } } ] }
Ad-hoc querying and sorting does not fit well into a database like DynamoDB, which is typically designed for a well-known set of access patterns. Due to this, the DynamoDB data source presents some limitations when used with the User Management and Dynamic Client Registration services.
accounts(...)
sorting
email
STARTS_WITH
filtering
ENDS_WITH
dynamicallyRegisteredClients(...)
templateClient
When a GraphQL query uses an unsupported feature, a GraphQL error message is returned. The errors.extensions attribute contains the details about the unsupported feature.
errors.extensions
{ "errors": [ { "message": "At least 1 filter key must be defined", "locations": [], "extensions": { "classification": "operation-not-supported", "not-supported-cause": "FILTERING_ABSENT" } } ] }
The possible not-supported-cause extension attribute values are listed in the table below:
not-supported-cause
ends_with
starts_with