# SAML Authentication

This article will cover how to configure SAML Authentication for **end-user applications** made in Airkit. This is a separate matter from configuring SAML Authentication to allow Builders to access the Console and Studio within your Organization. For more on configuring SAML authentication for Console and Studio Access, see [SAML SSO for an Organization](../administration/configuring-sso-access).

## Configuring SAML in the Console

### Establishing and Downloading the SAML Metadata File

In order to configure SAML access to Airkit applications, the SAML Assertion Metadata must be generated from the **Identity Provider** (IdP) of choice. It will be used to share configuration credentials between the IdP and the **Service Provider** (SP). The IdP metadata usually contains the IdP certificate, the entity ID, the redirect URL, and the logout URL.

Airkit requires the Metadata File to be formatted as an XML file with the following fields:

* `<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"` and/or `<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"`
* `<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>`; email is ideal but `user_lookup_attribute` can be used if the user’s email is on a different field
* `md:EntityDescriptor` tag with `entityID` attribute
* `md:IDPSSODescriptor` tag
* `X509Certificate` with cert inside

### Uploading the SAML Metadata File

This SAML Metadata file needs to be uploaded into the [Console](../console/console) in order to to define the IdP that will be receiving the SAML request. This is done under **Console > Settings > Organization**. In the **Authentication** section, click the **Create new** Button:

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-b50e2881d9501b13443e5c1f8937e8db3e309541%2Fsaml-authentication-v182-0.png?alt=media)

This will open the Inspector. Upload the SAML Metadata file in the space provided under **Properties**, and then click **Create** to generate a new SAML configuration out of the uploaded SAML Metadata file:

<figure><img src="https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-41a3e987f7317eb8a4e53c29b84929d10f6d08ca%2Fsaml-authentication-v182-1.png?alt=media" alt="" width="300"><figcaption></figcaption></figure>

### Configuring Your SAML Access

After uploading a Metadata File, you can view and configure properties associated with your SAML Authentication process.

* **User Lookup Attribute** (_editable_): This field is used when configuring SAML for Organization authentication. For more on configuring SAML authentication for Console and Studio Access, see [SAML SSO for an Organization](../administration/configuring-sso-access).
* **Canvas only URL ACS** (editable\*): The Starting Link of the application that requires SAML authentication.
* **ACS** (_static_): The ACS (Assertion Consumer Service) URL that defines the endpoint where the IdP will redirect users after they are authenticated. This is defined in the SAML Metadata File and cannot be edited in the Inspector.
* **Entity Id** (_static_): The globally unique name for the SAML entity, i.e., your Identity Provider (IdP) or Service Provider (SP). This is defined in the SAML Metadata File and cannot be edited in the Inspector.

<figure><img src="https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-84d87d33a8d0b95e93fb04341ebd67952a8523e3%2Fsaml-authentication-v182-2.png?alt=media" alt="" width="400"><figcaption></figcaption></figure>

## Configuring SAML within an Application

### Connecting Your Application with the Metadata

To require SAML authentication in order to access an application, open the app in the [Studio](../studio/studio) and toggle over to [Settings](../studio/builder-bar/settings). Under **Global > App Authentication Type** select **Secure App**, and make sure the **Authentication Method** is set to **Custom**. Finally, click the dropdown under SAML and select the relevant XML file.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-95b52d9715356664d2fea8ed53caaf21991d2669%2Fsaml-authentication-v182-3.png?alt=media)

All SAML Metadata Files that have been configured in the Console will be available for selection.

### Connecting the IdP to the Application

Once you have completed the content of the application, save your changes [publish](../building-apps/publishing/publishing-your-application) your application.

The [Starting Link](../concepts/journeys/linking-to-journeys) is the URL that your IdP should redirect users back to after they authenticate. The designation of this URL is different in each IdP. For instance, Okta calls it “Single Sign On URL,” Auth0 calls it the “Application Callback URL,” and OneLogin calls it the “ACS (Consumer) URL”. Please refer to the documentation and settings for your specific IdP for where to provide this URL.

After publishing your application and saving the URL to the IdP, users should be redirected to authenticate before using the application.

### On Authentication Success

After setting up you OAuth authentication, go to **Connections Builder** and click on the **On Authentication Success** Event.

The “On Authentication Success” Event will run when the user is authenticated. On this Event, there is the `event` namespace where you can access data about the user.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-9ad476cd6e5f975c92f858fb4087b7152266b7ae%2Fsaml-authentication-v182-4.png?alt=media)

For more on how to conceptualize Events, see [Events](../studio/events).

## Example SAML Authentication

\[block:embed] { "html": "\<iframe class="embedly-embed" src="//cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2F4Q4Et2Uv1Y4%3Ffeature%3Doembed\&display\_name=YouTube\&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D4Q4Et2Uv1Y4\&image=https%3A%2F%2Fi.ytimg.com%2Fvi%2F4Q4Et2Uv1Y4%2Fhqdefault.jpg\&key=f2aa6fc3595946d0afc3d76cbbd25dc3\&type=text%2Fhtml\&schema=youtube" width="640" height="480" scrolling="no" title="YouTube embed" frameborder="0" allow="autoplay; fullscreen" allowfullscreen="true">", "url": "https://www.youtube.com/watch?v=4Q4Et2Uv1Y4\&feature=youtu.be", "title": "Auth0 SAML auth Example", "favicon": "https://www.youtube.com/s/desktop/bc7edae9/img/favicon.ico", "image": "https://i.ytimg.com/vi/4Q4Et2Uv1Y4/hqdefault.jpg", "provider": "youtube.com", "href": "https://www.youtube.com/watch?v=4Q4Et2Uv1Y4\&feature=youtu.be" } \[/block]
