Overview

The OAuth 2.0: SAML Bearer Assertion as Authorization grant is an authentication type that requests access to an API on behalf of a signed in user, similar to the OAuth 2.0: Authorization Code grant. However, instead of redirecting the user to the Authorization Server for authorization, this authentication type makes the token request when the user signs into Appian using SAML for Single Sign-On. Designers can use this authentication type with HTTP and OpenAPI connected systems.

This article provides detailed information about how Appian can connect to systems that use the SAML Bearer Assertion as Authorization Grant. See also:

• To learn about connected system objects, see Connected System Object.
• To learn about the Authorization Code Grant, see OAuth 2.0: Authorization Code Grant.
• To learn about the Client Credentials grant, see OAuth 2.0: Client Credentials Grant.

Token Request Sequence

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 as Authorization Grant. There are four main roles in this sequence:

• Identity Provider (IdP) - The provider of identity information and authentication.
• Client - The system initiating the resource request. In this case, Appian.
• Authorization Server - The server that is ensuring that the user requesting resources has the proper permissions.
• Resource Server - The server that holds the desired resources.

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, it will immediately pass the SAML bearer assertion (along with the Client ID, Client Secret, and Scope set in the connected system) to the authorization server at the Token Request Endpoint. Appian will always pass the SAML bearer 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.

Access Token Expiration

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.

Important Design Considerations

There are several important design considerations when using the OAuth 2.0: SAML Bearer Assertion as Authorization Grant.

Registration in the Third-Party Systems

In order for Appian to successfully connect to the desired resources, you will need to:

1. Configure SAML for Single Sign-On.
2. Configure your third-party system to trust your Identity Provider.
3. Register the connection to Appian in the third-party system.
   • This is typically done under a third party system's Developer UI. The terminology varies, but registration usually requires creating an application or project in that system.

When establishing trust and registering an app or project in a third-party system a few things need to be considered:

• Access to the Identity Provider: In order to configure SAML for Single-Sign on and establish trust between your IdP and Service Provider, you will need to select an appropriate user to sign into the IdP and set everything up.
• Access to the third-party application or project: Because the OAuth 2.0 application or project in the third-party system will contain a client secret, an appropriate user should be selected to register the application or project. They may also need to upload the public key obtained from the IdP.
• Determine where scope should be defined: A registered application's scope may need to be configured in Appian or in the registered application. Be sure to refer the other system's documentation to know where to define scope.
• Trust between the authorization server and Identity Provider: The authorization server will need to be configured to trust your identity provider and accept the Audience URI specified in the SAML assertion. This will be configured in different ways depending on the IdP and authorization server that you use. The Service Provider Entity ID configured in the Admin Console for a SAML Identity Provider will need to match that Audience URI.

Parameters Set in the Connected System

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*	Optional. 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 as Authorization Grant. This authentication type only works with HTTPS endpoints that start with https://.

*This value is included in import customization files so that you can specify a different value for each environment.

Sign out and back in before testing the integration

Once the connected system has been configured and saved, the Appian developer will need to sign out and back in before integrations can be tested. This is the only way to retrieve the SAML Bearer Assertion and initiate that initial token request.

If the authorization server returns a refresh token, then it can be used for subsequent token refreshes until it expires. The Test Refresh Token button will only ever return Success if the authorization server returns a refresh token.