# Azure AD OIDC Setup Guide If you'd like to set up the ability to sign in to your Spacelift account using an OIDC integration with Azure AD, you've come to the right place. This example will walk you through the steps to get this setup, and you'll have single sign-on running in no time! ### Pre-requisites * Spacelift account, with access to admin permissions * Azure account, with an existing Azure Active Directory * You'll need permissions to create an **App Registration** within your Azure AD {% hint style="info" %} Please note you'll need to be an admin on the Spacelift account to access the account settings to configure Single Sign-On. {% endhint %} ### Configure Account Settings You'll need to visit the Spacelift account settings page to set up this integration, from the navigation side bar menu, select "Settings." ![](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2FbUc29SIelZ5BOpegEucJ%2FScreen%20Shot%202022-07-01%20at%204.12.30%20PM.png?alt=media\&token=fc936906-984d-4a26-9d2a-b5d42ca5a266) ### Setup OIDC Next, you'll want to click the Set Up box underneath the "OIDC Settings" section. This will expand some configuration we will need to fill out in a few minutes, which we will be obtaining from Azure. For now, **copy the authorized redirect URL** as we will need to provide Azure this URL when configuring our Azure App Registration within your Azure AD. ![](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2FUQah8uGthHUNGAmTH4s7%2FScreen%20Shot%202022-07-01%20at%204.16.00%20PM.png?alt=media\&token=275f9c2c-95c3-43f0-ad5e-0a4735bfa751) ### Azure Portal: Navigate to Azure Active Directory Within your Azure Account, navigate to your Azure Active Directory where you'd like to setup the OIDC integration for. In this guide, we are using a Default Directory for example purposes. ![Navigate to your Azure Active Directory.](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2FYGqRXzXsNurC9fzu6g7b%2F1-azure-navigate-to-azure-ad.png?alt=media\&token=fdda3022-cdf1-4467-8921-442d9a1820d5) ### Azure AD: Create an App Registration While you are within your Active Directory's settings, click on **App registrations** from the navigation, and then select **New registration**. ![Click on App Registrations, then click New Registration.](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2F5u06xeTMIIlDS2ORmWVe%2F2-azure-ad-new-registration.png?alt=media\&token=871212fb-1255-4e65-a65e-671fdaa775d0) ### Azure AD: App Registration Configuration Give your application a name - Spacelift sounds like a good one :clap: Configure your supported account types as per your login requirements. In this example, we are allowing Accounts in this organizational directory access to Spacelift. Remember the **authorized redirect URL** we copied earlier from Spacelift? We'll need that in this step. You'll want to paste that URL into the **Redirect URI** input as shown. Make sure you select **Web** for the type. Click **Register**. ![Give your App Registration a name. Configure the redirect URI.](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2FLj74g8z17DEh1k7VMUDz%2F3-azure-create-app-integration-step-1.png?alt=media\&token=508d3620-7c7f-44e6-8279-8da3975ba55b) ### Azure AD: Add UPN Claim Start by navigating to the **Token configuration** section of your application. ![](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2FcUXXlEeW3gX7hGdnVRfe%2Fimage.png?alt=media\&token=afa50900-0faa-4b40-b898-6f67e163bb5e) Click the **Add optional claim** button, choose the **ID** token type, and select the **upn** claim: ![](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2FulYRliLmeHsK9eS5etQg%2Fimage.png?alt=media\&token=ed99ed85-ca8e-477d-ad8b-91a4bf2f4047) Click the **Add** button, making sure to enable the **Turn on the Microsoft Graph profile permission** checkbox on the popup that appears: ![](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2F4uu75XSEiGXVMolLCslV%2Fimage.png?alt=media\&token=451366fb-c169-4782-9059-9be58dc735a3) ### Azure AD: Configure App Credentials Navigate to the **Certificates & secrets** section of your application. ![Navigate to Credentials & secrets.](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2FAezk2jQumx4Ce24FBPHD%2F3-azure-navigate-to-credentials.png?alt=media\&token=470e54cc-7510-404d-a979-64ef7f484bb4) Click the **New client secret** button. ![Click New client secret.](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2F2mwgNk1lt3D2RiiNNQ3T%2F4-azure-new-client-secret.png?alt=media\&token=0dee3790-59fb-4104-960f-6b1fc0e13ed9) Give your secret a **Description**. Define an **Expires** duration**.** {% hint style="info" %} In this example, we are using 6 months for **Expires.** This means you will need to generate a new client secret in 6 months for your OIDC integration. {% endhint %} Click **Add.** ![Define client secret Description and Expires duration.](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2F9WAtdMhSx3hwzJfntc6q%2F5-azure-new-secret.png?alt=media\&token=356ffbf1-72b0-4136-8ed7-36804e0406b1) Now that we have the Client secret setup for our application, we'll need to take the **Value** and copy this into our Spacelift OIDC settings within the **Secret** input. * **Value** within Azure AD = Spacelift's **Secret** input {% hint style="info" %} Don't click Save in Spacelift just yet, we still need to get the Client ID and Provider URL for your application. {% endhint %} ![Copy the Value to your Spacelift OIDC settings as the "Secret".](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2F0OG20jza8W8kEzIVUcFe%2FScreen%20Shot%202022-04-14%20at%2011.03.31%20AM.png?alt=media\&token=2e1cbfc5-8997-4068-b827-25f21517ab61) The best way we've found to obtain the Client ID and Provider URL is to perform the following steps: Click on **Overview** within your Azure App. On this page **Application (client) ID.** Copy this value to Spacelift as the Client ID Next, Click **Endpoints** which should expand a page with the endpoints for your App. Copy the portion of the **OpenID Connect metadata document** URL that is highlighted as shown in the screenshot, and paste the value into Spacelift as the **Provider URL**. ![Copy the OpenID Connect metadata document URL.](https://3862190545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LshwwDZmA4HXN0k9e8O%2Fuploads%2FzbSGl5BsAhPnqnbmZVaS%2F6-azure-obtain-provider-url.png?alt=media\&token=84fd5b42-d438-4cb5-b7cf-dcaa551aed72) In summary, here are the values that should be copied over to Spacelift: * Application (client) ID within Azure AD => Client ID on Spacelift * Secret Value you generated => Secret input on Spacelift * OpenID Connect metadata document URL => Provider URL on Spacelift Click **Save.** ### Azure AD OIDC Setup Completed That's it! Your OIDC integration with Azure AD should now be configured (as per this example). Feel free to make any changes to your liking within your Azure AD App Registration configuration for the app that you just created. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://spacelift-io.gitbook.io/spacelift/integrations/single-sign-on/azure-ad-oidc-setup-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.