GraphQL¶

GraphQL is a graph based JSON API over HTTP. It exposes a strongly typed schema with query and mutation operations. In User Management, the graph is based on the account, with sub-elements such as linked accounts and devices that belong to that particular account. Moreover, the User Management GraphQL API allows to manage buckets linked to user accounts.

Queries and Mutations¶

The operations are categorized into two types: query and mutation.

The possible queries for accounts are:

Listing 188 GraphQL Queries¶

accountByUserName(userName: String!) : Account

accountById(accountId: String!) : Account

accountByEmail(email: String!) : Account

accountByPhoneNumber(phoneNumber: String!) : Account

accounts(
    activeAccountsOnly: Boolean = true
    first: Int
    after: String
    sorting: Sorting = {sortOrder: DESCENDING}
    filtering : Filtering
) : AccountConnection!

If a Credential Manager is configured with a credential policy, the following queries are also available:

Listing 189 GraphQL Credential Policy Rules Queries¶

credentialPolicyRulesStateByUserName(userName: String!) : CredentialPolicyRulesState

If a bucket datasource is configured in the User Management profile, the following queries are also available:

Listing 190 GraphQL Queries¶

bucketsByUserName(
    userName: String!
    purposes: [String!]!
) : [Bucket!]!

As can be determined from the names, they operate on singular or plural accounts.

The account type provides information about the account (attributes of an account) as well as devices and dynamic clients associated with that account. The inclusion of dynamic clients is disabled by default and can be enabled by setting include-dynamic-clients-in-graph-QL-account-response to true under /profiles/profile (user-management-service)/settings/user-management-service/include-dynamic-clients-in-graph-QL-account-response.

The possible mutations for account related data available are:

Listing 191 GraphQL Mutations¶

createAccount(input: CreateAccountInput!): CreateAccountPayload

updateAccountById(input: UpdateAccountByIdInput!): UpdateAccountByIdPayload

validatePasswordAndUpdateAccountById(input: ValidatePasswordAndUpdateAccountByIdInput!): ValidatePasswordAndUpdateAccountByIdPayload

deleteAccountById(input: DeleteAccountByIdInput!): DeleteAccountByIdPayload

deleteLinkFromAccountByAccountId(input: DeleteLinkFromAccountByAccountIdInput!): DeleteLinkFromAccountByAccountIdPayload

deleteDeviceFromAccountByAccountId(input: DeleteDeviceFromAccountByAccountIdInput!): DeleteDeviceFromAccountByAccountIdPayload

deleteOptInMfaFactorFromAccountByAccountId(input: DeleteOptInMfaFactorFromAccountByAccountIdInput!): DeleteOptInMfaFactorFromAccountByAccountIdPayload

resetOptInMfaStateByAccountId(input: ResetOptInMfaStateByAccountIdInput!): ResetOptInMfaStateByAccountIdPayload

addDeviceToAccountByAccountId(input: AddDeviceToAccountByAccountIdInput!): AddDeviceToAccountByAccountIdPayload

updateDeviceFromAccountByAccountId(input: UpdateDeviceFromAccountByAccountIdInput!): UpdateDeviceFromAccountByAccountIdPayload!

If a Credential Manager is configured with a credential policy, the following mutations are also available:

Listing 192 GraphQL Credential Policy Rules Mutations¶

setCredentialPolicyRulesStateByUserName(input: CredentialPolicyRulesStateInput!): CredentialPolicyRulesState

Only the state of rules which are configured in the relevant Credential Policy may be modified.

If a bucket datasource is configured in the User Management profile, the following mutations are also available:

Listing 193 GraphQL Mutations¶

deleteBucketByUserName(input: DeleteBucketByUserNameInput!): DeleteBucketByUserNamePayload

Introspection¶

GraphQL comes with a schema that can be introspected directly from the endpoint. Most graphql clients knows how to perform this operation and how to interpret the results. It’s important to note that even the introspection of the schema is oauth protected and requires appropriate permissions to be allowed.

Authorization¶

The GraphQL API requires a valid Access Token from the associated OAuth Profile. This token is used to authorize the request. The authorization is handled by the configured authorization manager. If no authorization manager is configured, then no access will be given. It is recommended to use the groups authorization manager and to provide a value for the groups claim in the access token that maps against the rules in the authorization manager. See how GraphQL operations map to CRUD access operations in authorization manager rules.

Custom Attributes¶

The User Management profile allows the addition of custom attributes that extend the predefined account type schema. Additional attributes consist of attribute name and attribute type (attribute type represents the data type of an object and must be one of the following: String - text-based attribute, Boolean - true/false, Long - number-based attribute, Object - custom JSON Object). The configured attributes are added to all queries and mutations for an account and are present when introspecting the GraphQL schema. The custom attributes can be configured in the User Management profile settings and are optional in all GraphQL account related queries and mutations.

Data Sources¶

The currently supported data sources for GraphQL are the JDBC, MongoDB and SCIM 2.0 data sources. There is limited support for DynamoDB, see the limitations.

More Details¶

For more details about how to work with the GraphQL APIs see the developer documentation.