Authenticate with federated user accounts
Follow the instructions in this topic if you are building an application intended to interface with a wide vatiety of tenants, each of which might use a different IDP with a variety of possible configurations, or if your application needs to be able to request a set of tokens from a tenant interfaced with a federated identity management system that is not able to provide tokens directly.
Requests against the API must be authenticated and made over HTTPS. If these requirements are not met, the request fails.
If you are using a token provided by an OAuth compatible federated identity management (IDP) system that has been properly interfaced with your tenant, include the federated token as your access_token
value just as you would use a normally generated access_token
.
Successful token requests generate an access token and a refresh token. The access token is usable from the moment it is generated until the number of seconds defined by expiresInSeconds
elapses. The refresh token can be used to generate new access tokens and refresh tokens until the session expires. Refresh tokens expire after 8 hours.
Prerequisites
The following must be in place before an application can authenticate with federated user accounts:
- Federation must be configured correctly for each tenant accessed by your application.
- Users must be able to log in to the UI using a tenant's configured IDP.
- Your application must expose a URI to which responses and token information is directed, and this URI must be whitelisted in each tenant. To whitelist a URI for this purpose, go to Application Setup > System settings > Global Values in the UI and update the following tenant-specific system setting:
global.oAuth.authCode.redirection.uris
.
Log in and generate tokens
In your application, route to the following URI:
https://<<hostName>>/oauth2/authorize?response_type=code&client_id=<<client ID>>&redirect_uri=<<whitelisted URI>>
Note: Use the tenant's
hostName
configured for users with IDP accounts. This portion of the URI is set up as part of a tenant's federation configuration.
Important: The query parameters in the URI are case-sensitive and must be entered exactly as specified:
response_type
,client_id
, andredirect_uri
.
This URI displays a login screen for the IDP user if the user is not already logged in. After the user logs in, the tenant redirects to to URI defined in redirect_uri
and includes the following:
https://<<whitelisted URI>>/?code=<<code>>&iss=<<iss URI>>&client_id=<<client ID>>
code
: An authentication string required for the next call in the sequence to generate an access token.iss
: The authentication Server Issuer Identification.client_id
: A string representing the tenant's client ID.
Note: The authentication
code
has a lifetime of 5 minutes and can only be used once in a call to generate tokens.
In your application, POST a call to the following authentication URI:
https://<<hostName>>/api/authentication/access_token
Include the following HTTP headers:
Content-Type : application/x-www-form-urlencoded
Include the following in the request body:
redirect_uri=<<whitelisted URI>>
client_id=<<client ID>>
client_secret=<<client password>>
grant_type=authorization_code
code=<<code>>
A successful call to the authentication URI returns:
access_token
: A string representing the access token.refresh_token
: A string used to obtain a new access token when the current access token becomes invalid or expires. Refresh tokens are optional, are issued at the discretion of the server, and expire after 8 hours.scope
: The server uses this response parameter to inform the client of the scope of the issuedaccess_token
.token_type
: Defines the type of token profile issued by the server, such asBearer
ormac
. This enables the client to successfully utilize theaccess token
.expires_in
: Lifetime in seconds of theaccess_token
.
Even though your tokens are time-limited, they are very powerful. Do not share your access_token
or refresh_token
. Protect them as you would a username and password combination.
Refresh a token
To use a refresh token to generate a new access token and refresh token based on the credentials of the user who generated the initial refresh token, POST a call to the following authentication URI:
https://<<hostName>>/api/authentication/access_token
Include the following HTTP headers:
Content-Type : application/x-www-form-urlencoded
Include the following in the request body:
refresh_token : <<refreshToken>>
client_id : <<client ID>>
client_secret : <<client password>>
grant_type : refresh_token
auth_chain : OAuthLdapService
A successful call to the authentication URI returns:
access_token
: A string representing the access token.refresh_token
: A string used to obtain a new access token when the current access token becomes invalid or expires. Refresh tokens are optional, are issued at the discretion of the server, and expire after 8 hours.scope
: The server uses this response parameter to inform the client of the scope of the issuedaccess_token
.token_type
: Defines the type of token profile issued by the server, such asBearer
ormac
. This enables the client to successfully utilize theaccess token
.expires_in
: Lifetime in seconds of theaccess_token
.
Make an API call
If you are ready to use your generated access token to make an API call against a tenant, proceed to the Quick Start topic.
Updated 8 months ago