The User Management Service provides calling apps the ability to authenticate users through any of the following identity providers: Google, Microsoft, Amazon Cognito. After going through the authentication process with the respective identity provider, users are signed into your app and can use its resources. More specifically, the User Management Service provides the following features:
- Sign in users
- Sign out users
- Exchange a refresh token for an access token, if the latter has expired
- Return the ID of a user based on an input access token.
Access info
|
|
| Endpoint |
https://user-management-api.socrate.io/graphql |
| Required access keys |
App-level service access key |
| Pricing |
Please contact us for details at contact@bitsoftware.ro |
| Notes |
To call the service, the access key must be provided in the x-api-key header of the HTTP request. If you are using the GraphQL console, you can view the service’s documentation and schema only after entering an access key. Make sure that the scope of the key allows access to the queries and mutations that you require. For example, to grant the key access to all queries and mutations, the keys’s scope must be set to user-management-api:query:* user-management-api:mutation:*. |
Prerequisites
- Depending on the identity provider you want to use, your app must be registered on the Google Cloud platform, Microsoft Azure platform, or Amazon Web Services (AWS) platform (Cognito). More specifically, your app must be configured to have a consent screen that will be displayed to users when they click a Sign in with… button and proceed to the authentication process with the respective provider.
- Your app must be capable to issue an authorization request to Google, Microsoft, or AWS, and obtain a JSON Web Token (JWT) in the response (also known as “id token”). The JWT is required to sign the user into your app, as input parameter to the
signIn mutation.
- Make sure to update your SBS app with the client secrets as obtained from the respective identity provider. In case of Google or Microsoft, this includes an application ID, a client ID, a client secret, and some other data. In case of Cognito, this includes a User Pool ID and Client ID. You can perform this step either from a web interface (SBS Console) or programmatically from the Account API. For more information, see Configure Google OAuth 2.0 Client Secrets, Configure Azure OAuth 2.0 Client Secrets, Configure Cognito OAuth 2.0 Client Secrets.
Queries
getUserId
Returns the ID of the user based on the access token provided as input.
Arguments
| Argument |
Type |
Description |
| access_token |
String! |
The access token obtained from the authorization server. |
Result
The SBS-generated ID of the user signed into your app.
user
Returns a user by their ID.
Arguments
| Argument |
Type |
Description |
| id |
ID! |
Mandatory. The ID of the user to be retrieved. |
Result
See the User type.
users
Arguments
| Argument |
Type |
Description |
| filter |
UsersFilter |
Optional. Lets you specify user filtering options, as UsersFilter input. |
| nextToken |
String |
Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the UsersResult type. |
All attributes of the UsersFilter object are optional. If you specify multiple options, they will be connected by a logical AND.
| Attribute |
Type |
Description |
| email |
EmailAddress |
Optional. If provided, results are filtered by this email address. |
| provider |
Provider |
Optional. If provided, results are filtered by this provider. Valid values: GOOGLE, MICROSOFT, COGNITO. |
| createdAt |
DateFilter |
Optional. If provided, only users created within this date range are retrieved. |
| Attribute |
Type |
Description |
| from |
Date |
Optional. The start date of the date range. |
| to |
Date |
Optional. The end date of the date range. |
Result
UsersResult type
| Attribute |
Type |
Description |
| items |
User |
The list of users, where each user is a User type. |
| nextToken |
String |
If null, then the query has reached the end of the list of records that match the query criteria. If not null, then use this value in the nextToken input argument to obtain the next page. |
User type
| Attribute |
Type |
Description |
| id |
ID |
The SBS-generated identifier of the user. |
| name |
String |
The user’s name obtained from the identity provider. |
| family_name |
String |
The user’s family name obtained from the identity provider. |
| given_name |
String |
The user’s given name obtained from the identity provider. |
| email |
EmailAddress |
The user’s email address obtained from the identity provider. If the provider is MICROSOFT, this value could be a string which is not necessarily a verified email. To set this value to a verified email, run the setVerifiedEmail mutation. |
| picture |
Uri |
The URI, obtained from the identity provider, at which the user’s picture is available. |
| provider |
Provider |
The identity provider, which can be one of the following: GOOGLE, MICROSOFT, COGNITO. |
| googleUserInfo |
GoogleUserInfo |
The user’s information retrieved from Google JWT token’s payload, as a GoogleUserInfo object. |
| microsoftUserInfo |
MicrosoftUserInfo |
The user’s information retrieved from Microsoft JWT token’s payload, as a MicrosoftUserInfo object. |
| createdAt |
DateTime |
The date and time when the user record was created in SBS. |
GoogleUserInfo type
| Attribute |
Type |
Description |
| iss |
Uri |
The token’s issuer. |
| sub |
String |
The token’s subject (that is, to whom this token refers). |
| azp |
String |
The token’s authorized party (that is, the party to whom this token was issued). |
| aud |
String |
The token’s audience. |
| iat |
Float |
The timestamp when the token was issued. |
| exp |
Float |
The timestamp when the token expires. |
| email |
EmailAddress |
The email claim stored in the token. |
| email_verified |
Boolean |
Specifies if the email is verified (true), false otherwise. |
| name |
String |
The user’s name claim stored in the token. |
| picture |
Uri |
The user’s picture URI claim stored in the token. |
| given_name |
String |
The user’s given name claim stored in the token. |
| family_name |
String |
The user’s family name claim stored in the token. |
| locale |
String |
The user’s locale. |
MicrosoftUserInfo type
| Attribute |
Type |
Description |
| sub |
String |
The token’s subject (that is, to whom this token refers). |
| name |
String |
The user’s name claim stored in the token. |
| email |
EmailAddress |
The email claim stored in the token. |
| preferred_username |
String |
The user’s preferred username claim stored in the token. |
| aud |
String |
The token’s audience. |
| iat |
Float |
The timestamp when the token was issued. |
| exp |
Float |
The timestamp when the token expires. |
version
Returns the API version.
Mutations
generateEmailVerificationCode
Generates a numeric code that is valid for 5 minutes. The generated code must be supplied as input to the setVerifiedEmail mutation in order for it to succeed.
Arguments
| Attribute |
Type |
Description |
| userId |
ID! |
Mandatory. The ID of the user whose email is to be verified. |
| email |
EmailAddress! |
Mandatory. The email address to be verified. Note that the user’s email provider should be MICROSOFT. |
Result
The generated verification code, as a string.
regenerateAccessToken
Obtains from the identity provider new tokens (including an access token), based on the refresh token supplied as input.
Arguments
| Attribute |
Type |
Description |
| refresh_token |
String! |
Mandatory. Supplies the refresh token to be used as input. |
Result
Token type
| Attribute |
Type |
Description |
| access_token |
String |
The access token obtained from the identity provider. |
| expires_in |
Float |
The access token’s expiry date. |
| refresh_token |
String |
The refresh token obtained from the identity provider. |
| user |
User |
See the User type. |
| newUser |
Boolean |
Returns true if the user signs in for the first time, false otherwise. This information is useful if you would like to take some action when a new user signs in to the application (for example, send a welcome email). |
setVerifiedEmail
When you sign in a user and the provider is MICROSOFT, the value returned in the User.email response field is not necessarily a verified email (for example, it may be a string such as a phone number of some user alias). If your app’s business requirements mandate that users have a verified email address, then you should implement an email validation outside of SBS, with the goal of obtaining the user’s verified email address. For example, your app may prompt the user to enter their email address and then send an email to their inbox. If the user confirms that they own the inbox (perhaps by clicking a verification link in the email message), then their email address is considered verified. Once you have the verified email address, run this mutation to set the email as verified in SBS as well.
Arguments
| Attribute |
Type |
Description |
| userId |
ID! |
Mandatory. The ID of the user whose email address is to be updated. |
| email |
EmailAddress! |
Mandatory. The verified email address. |
| verificationCode |
String! |
Mandatory. The verification code generated by the generateEmailVerificationCode mutation. |
Result
See the User type.
signIn
Authenticates a user based on the JSON Web Token (JWT) supplied as input.
Arguments
| Attribute |
Type |
Description |
| input |
SignInInput! |
Mandatory. The input to the sign in, as a SignInInput type. |
| Attribute |
Type |
Description |
| provider |
Provider! |
Mandatory. Specifies the identity provider. Valid values: GOOGLE, MICROSOFT, COGNITO. |
| id_token |
String! |
Mandatory. The JSON Web Token (JWT) obtained from the identity provider. |
Result
See the Token type.
signOut
Signs out a user based on the refresh token supplied as input.
Arguments
| Attribute |
Type |
Description |
| refresh_token |
String! |
Mandatory. The refresh token to be used as input. |
Result
See the User type.