The OAuth 2.0: SAML Bearer Assertion Flow is an authentication type that requests access to an API on behalf of a signed in user, similarly to the OAuth 2.0: Authorization Code grant. However, instead of redirecting the user to the Authorization Server for manual authorization, this authentication type automatically uses the SAML assertion returned by the Identity Provider to make a token request when the user signs into Appian via SAML for Single Sign-On. Designers can use this authentication type with HTTP and OpenAPI connected systems.
Specifically, Appian supports the use of SAML Assertions as Authorization Grants. For this flow, the value of the grant_type parameter in the token request will be set to urn:ietf:params:oauth:grant-type:saml2-bearer
.
This article provides detailed information about how Appian can connect to systems that use the SAML Bearer Assertion Flow. See also:
The OAuth 2.0 framework is defined by the ITEF RFC 6749 standard.
This standard establishes the sequence of steps involved with the SAML Bearer Assertion Flow. There are four main roles in this sequence:
The following sequence diagram describes the steps involved in a successful authorization, with a resource returned to the client.
The first part of the proces involves a user signing into Appian via the configured Identity Provider (IdP). Upon success, the IdP returns a SAML response that contains a SAML bearer assertion. This piece was simplified for the purposes of this flow chart, but the detailed flow can be seen on the SAML for Single Sign-On page.
As soon as Appian gets that SAML bearer assertion, it decrypts it if necessary and signs the user in. Then, for each Connected System that uses the OAuth 2.0: SAML Bearer Assertion Flow, Appian will immediately pass the SAML bearer assertion (along with the Client ID, Client Secret, Scope, and any Additional HTTP Headers set in the connected system) to the authorization server at the Token Request Endpoint. Appian will always pass the SAML assertion unencrypted. If the authorization server successfully authorizes the credentials, it will return an access token and optionally a refresh token.
From there, the access token will allow the client to request whatever resources were approved by the user. When it expires, if there's a refresh token, it will try to fetch another access token. However, if there is no refresh token or the refresh token expires, the user will need to sign out and back in to fetch a new SAML bearer assertion in order to reauthorize. For this reason, you should set your refresh token to last as long as you'd expect a user to realistically stay signed in for to ensure the best user experience. Refresh token duration is configured in the authorization server.
Note: If the token request fails on user sign in, the only way to retry is for the user to sign out of Appian and sign back in.
Once someone has an access token, future requests will be granted until (1) the server revokes permission, or (2) the access token expires.
Appian considers an access token to be revoked or expired when it's used to call an integration and the integration returns a status code of 401
, 403
, or 404
. At that point, if Appian has a refresh token, it will automatically call the Token Request Endpoint (or Token Refresh Endpoint if that field is populated) to fetch another access token. If that call is successful, Appian will use the new access token to automatically retry the integration call. If the token refresh fails, or if no refresh token was provided, you will need to manually sign out and back into Appian in order to reauthorize the client before Appian can access the specified resource.
There are several important design considerations when using the OAuth 2.0: SAML Bearer Assertion Flow.
Note: It is very important to review and understand the requirements in the third-party systems for a successful OAuth connection.
In order for Appian to successfully connect to the desired resources, you will need to:
When establishing trust and registering an app or project in a third-party system a few things need to be considered:
Once you've configured SAML for Single Sign-On and registered your third-party systems, there are still several important steps that need to be taken before users can integrate using the OAuth 2.0: SAML Bearer Assertion Flow.
Before any users can make token requests using the SAML Bearer Assertion Flow, a system administrator will need to go to the SAML Authentication page of the Admin Console and enable the checkbox labeled OAuth 2.0: SAML Bearer Assertion Flow. This will enable the token request on login for any users in the OAuth 2.0 SAML Bearer Assertion Users system group that use SAML for Single Sign-On.
In addition to enabling the SAML Bearer Assertion Flow in the Admin Console, a system administrator will also need to configure the OAuth 2.0 SAML Bearer Assertion Users system group to include any Users and Groups that should use the SAML Bearer Assertion Flow. Only users in this system group will make a token request upon login.
The SAML Bearer Assertion Flow can be used with HTTP and OpenAPI connected systems by selecting OAuth 2.0: SAML Bearer Assertion Flow
in the Authentication dropdown. This authentication type can be configured regardless of whether it's enabled in the Admin Console. However, the token requests will only be made when the OAuth 2.0: SAML Bearer Assertion Flow checkbox is enabled in the Admin Console and there are users in the OAuth 2.0 SAML Bearer Assertion Users system group.
When a user in the system group logs into Appian using SAML for Single Sign-On, a token request will be sent for each connected system that uses the OAuth 2.0 SAML Bearer Assertion Flow authentication type, regardless of object security. Token requests will be made to the URL specified in the Token Request Endpoint field, as described in the Token Request Sequence diagram above.
The following parameters from the third-party system will need to be entered into the connected system. Refer to the third-party's documentation for more information.
Field | Description |
---|---|
Client ID* | Required/Sensitive. ID provided by the third-party system during the registration process. |
Client Secret* | Required/Sensitive. The password provided by the third-party system during the registration process. This field is masked to prevent unauthorized users from seeing and should be treated as a password. |
Scope | Optional. Defines what resources need to be accessed from the resource server. Depending on what system Appian is connecting to, permissions may be configured in the Developer UI rather than using a scope. In these cases, a default scope value may be specified in their documentation. |
Token Request Endpoint* | Required. The endpoint that provided the access token for the specified resources. This value can typically be found in the third-party's documentation. This authentication type only works with HTTPS endpoints that start with https:// . |
Token Refresh Endpoint* | A separate endpoint that provided the access tokens in exchange for refresh tokens. When left blank, the Token Request Endpoint will be used for token refresh instead. This value is not used by most implementations of the OAuth 2.0 SAML Bearer Assertion Flow. This authentication type only works with HTTPS endpoints that start with https:// . |
Additional HTTP Headers* | Defines additional HTTP headers that Appian will send with token requests. These will be sent to both the Token Request Endpoint and the Token Refresh Endpoint. |
* This value is included in an import customization file so that you can specify a different value for each environment. Sensitive values will not be exported in the import customization file and must be added manually. Required fields must have a value upon import or else import will fail. For more information on import/export behavior, see the Connected Systems Object page.
Testing requires users to sign out and back in. This is the case because logging in via SAML for Single Sign-On is the only way to retrieve an updated SAML Bearer Assertion and initiate the initial token request to the Token Request Endpoint.
OAuth 2.0: SAML Bearer Assertion Flow