# SAML configuration
#### SAML provides secure single sign-on by integrating an identity provider (IdP) with GitProtect, allowing users to authenticate with centralized credentials while ensuring controlled access and compliance.
***
## Overview
**GitProtect** integration works via the **SAML** 2.0 protocol, meaning any platform supporting this protocol can be integrated with **GitProtect**.
The configuration process is straightforward and requires only the entity ID, metadata URL, reply URL, and logout URL (the names may vary depending on the naming conventions used by specific platforms). In some cases, a certificate and a private key are also required.
***
## Configuration
{% hint style="danger" %}
Do not test the integration in the IdP panel (for example, the **Azure Portal**) as it will initiate login from the IdP panel.
{% endhint %}
Below table illustrates **SAML** integration configuration for selected platforms, including [Auth0](#auth0), [Azure AD](#azure-a-d), [CyberArk](#cyberark), [Google](#google), [JumpCloud](#jumpcloud), [Okta](#okta), and [OneLogin](#onelogin).
{% tabs %}
{% tab title="Auth0" %}
### Configuration in Auth0
1. Open your **Auth0** admin dashboard, go to **Dashboard** > **Applications** > **Applications**, and hit **Create Application button** in the top-right corner of the screen.
2. In **Create application** window enter a unique, custom application name (in this example we'll be using **XoperoAuth0**), select **Regular Web Applications** option, and click **Create**:
3. In the newly created application window go to **Settings** tab, scroll down to the very bottom, and click **Advanced Settings** collapsible to expand it.
4. Go to the **Endpoints** tab and locate **SAML** section. Copy the **SAML Metadata URL** and save it for later— it will be needed for **GitProtect** configuration.
5. Scroll back to top and open the **Addons** tab, then toggle the **SAML2 WEB APP** button.
6. In the window that opens up open the **Settings** tab and enter the **Application Callback URL** as follows:
> ****/Auth/AssertionConsumerService
{% hint style="warning" %}
In the above address, change **GitProtectManagementServiceURL** to your unique **Management Service** URL. You can find it in your login URL— it's the first part of the address (i.e., in ******/authorization/login** the part highlighted in **red** is the URL you need to copy).
{% endhint %}
7. In the same tab, scroll down inside the code input field and uncomment 31st, 32nd and 33rd line, then edit line 32 as follows:
{% code overflow="wrap" %}
```
“callback”: "https://GitProtectManagementServiceURL/auth/SAMLLogoutResponse"
```
{% endcode %}
{% hint style="warning" %}
In the above address, change **GitProtectManagementServiceURL** to your unique **Management Service** URL. You can find it in your login URL— it's the first part of the address (i.e., in ******/authorization/login** the part highlighted in **red** is the URL you need to copy).
{% endhint %}
8. Once done, scroll down to the bottom of the addon window and click **Enable** button, then close the window to finish app configuration.
***
### Configuration in GitProtect
1. Login to your **Management Service** web panel, go to **Settings** (bottom-left corner in the left-hand side menu) and select **External Identity Providers**.
2. Click **Add new provider** button and fill in the details:
> **Name:** your own custom name, i.e., **Auth0**
>
> **Entity ID:** should be the same name you've set as application name in **Auth0** (in this example it's **XoperoAuth0**)
3. Next, paste the previously copied **SAML Metadata URL** in the **Metadata URL** field.
4. Add certificate and password if required.
5. Set up a default **Language** and **Role** for users with **Auth0** **SAML** authentication permissions.
6. Double-check the settings and hit **Save** at the bottom of **Add identity provider tab**.
7. Click **Save** to finish the setup. You can now log out and test your configured **SAML** login integration.
{% endtab %}
{% tab title="Azure AD" %}
### Configuration in Azure
1. Login to [portal.azure.com](http://portal.azure.com/), select **Azure Active Directory** and click **Enterprise applications**.
2. Hit the **New application** button and then **Create your own application**.
3. Enter a custom name for the app and select **Integrate any other application you don’t find in the gallery (Non-gallery)**.
4. Confirm the configuration and hit **Create** button.
5. Open the **Single sign-on** tab and select **SAML** method.
6. Click the **Edit** button in ① **Basic SAML Configuration** section to edit it.
7. Set up a unique **Identifier (Entity ID)** i.e., **SAMLTestAzure**
8. Enter the following URL in **Reply URL (Assertion Consumer Service URL)** section:
> ****/Auth/AssertionConsumerService
9. Change the **Logout Url (Optional)** to the following address:
> ****/auth/SAMLLogoutResponse
{% hint style="warning" %}
In the above address, change **GitProtectManagementServiceURL** to your unique **Management Service** URL. You can find it in your login URL— it's the first part of the address (i.e., in ******/authorization/login** the part highlighted in **red** is the URL you need to copy).
{% endhint %}
10. Double-check if the info you have entered is correct and click the **Save** button.
11. Next, click the **Edit** button in ② **Attributes & Claims** section and hit ➕**Add a group claim** button.
12. Select **All groups** and go to **Advanced options**. Check the **Filter group** box and fill in the fields as follows:
> **Attribute to match**: Display name\
> **Match with**: Prefix\
> **String**: XONE
13. Check the **Customize the name of the group claim** checkbox. Enter **xoperogroup** in the **Name** field and save your settings.
14. Go back to **SAML-based Sign-on** page and copy the **App Federation Metadata Url**.
15. Save your settings.
16. Open the **Users and groups** tab and click ➕ **Add user/group** button. Select users you want to be able to login to **GitProtect** and save your settings.
***
### Configuration in GitProtect
1. Login to your **Management Service** web panel, go to **Settings** (bottom-left corner in the left-hand side menu) and select **External Identity Providers**.
2. Click **Add new provider** button and fill in the details:
> **Name:** your own custom name, i.e., **Azure AD**
>
> **Entity ID:** should be the same name you've set in **Identifier (Entity ID)** in **Azure** (in this example it's **SAMLTestAzure**)
3. Next, paste the previously copied **App Federation Metadata Url** in the **Metadata URL** field.
4. Add certificate and password if required.
5. Set up a default **Language** and **Role** for users with **Azure** **SAML** authentication permissions.
6. Double-check the settings and hit **Save** at the bottom of **Add identity provider tab**.
7. Click **Save** to finish the setup. You can now log out and test your configured **SAML** login integration.
{% endtab %}
{% tab title="CyberArk" %}
### Configuration in CyberArk
1. Log in to your **CyberArk** account. Expand **Apps & Widgets** dropdown menu and select **Web Apps**.
2. Click **Add Web Apps** button in the top-right corner.
3. Go to **Custom** tab, find **SAML** on the list, and click the **Add** button next to it.
4. Confirm adding **SAML** as a web app.
5. You’ll be redirected to **SAML** web app settings. Start with setting up a custom name for the app (i.e., **XONESAML**).
6. Next, set up a unique **Application ID** in **Advanced** section and **Save** your settings (in this example we will be using **XONESAMLID**).
7. Open the **Trust** tab and copy **Metadata URL** in **Identity Provider Configuration** section (it will be needed later for **GitProtect** configuration).
8. Next, scroll down to **Service Provider Configuration** section, set it to **Manual Configuration**, and enter the following data:
> In **SP Entity ID / Issuer / Audience** type your previously defined **Application ID** (in this example it is **XONESAMLID**)
>
> In **Assertion Consumer Service (ACS) URL** enter:
>
> ****/Auth/AssertionConsumerService
>
> In **Single Logout URL** enter:
>
> ****/auth/SAMLLogoutResponse
{% hint style="warning" %}
In the above address, change **GitProtectManagementServiceURL** to your unique **Management Service** URL. You can find it in your login URL— it's the first part of the address (i.e., in ******/authorization/login** the part highlighted in **red** is the URL you need to copy).
{% endhint %}
Manual configuration overview.
9. Go to **SAML Response** tab and scroll down to **Script to set custom claims** section. Enter the following script and press the **Save** button:
{% code overflow="wrap" lineNumbers="true" %}
```xml
setFilteredAttributeArray("xoperogroup", LoginUser.RoleNames, "XONE.*");
setFilteredAttributeArray("xoperogroup", LoginUser.GroupNames, "XONE.*");
```
{% endcode %}
10. Head over to **Permissions** tab, click **Add** button, select all users you want to authorize to use SAML integration, and **Save** your settings.
***
### Configuration in GitProtect
1. Login to your **Management Service** web panel, go to **Settings** (bottom-left corner in the left-hand side menu) and select **External Identity Providers**.
2. Click **Add new provider** button and fill in the details:
> **Name:** your own custom name, i.e., **CyberArk**
>
> **Entity ID:** should be the same name you've set in **Application ID** in **CyberArk** (in this example it's **XONESAMLID**)
3. Next, paste the previously copied **Metadata URL** in the **Metadata URL** field.
4. Add certificate and password if required.
5. Set up a default **Language** and **Role** for the users with **CyberArk** **SAML** authentication permissions.
6. Click **Save** to finish the setup. You can now log out and test your configured **SAML** login integration.
XMS login page with CyberArk SAML integrity set up.
### Configuration in Google
1. Login to your **Google** admin console. Next, click the burger menu icon .png?alt=media) in the top-left corner of the screen and go to .png?alt=media)**Apps** > **Web and mobile apps**. Click **Add app** and select **Add custom SAML app** from the drop-down menu.
2. In the app details page create a custom name for your app and type it in **App name** field, then click **Continue**.
3. Next, click **DOWNLOAD METADATA** button under **Option 1: Download IdP metadata**. Upload the downloaded file to your web server and save its URL (it will be needed later for **GitProtect** configuration).
4. Click **Continue** and in the next window screen fill the **Service provider details** as follows:
> **ACS URL:**
>
> ****/Auth/AssertionConsumerService
>
> **Entity ID:** custom, globally unique name (in this example we'll be using **SAMLGOOGLE**)
>
> **Start URL (optional):** your **GitProtectManagementServiceURL**
{% hint style="info" %}
In the above address, change **GitProtectManagementServiceURL** to your unique **Management Service** URL. You can find it in your login URL— it's the first part of the address (i.e., in ******/authorization/login** the part highlighted in **red** is the URL you need to copy).
{% endhint %}
5. Once done, click **Continue** and on the next page hit **Finish**.
6. Back on the admin console main page, click the burger menu in the top-left corner, go to **Apps** > **Web and mobile apps**, then select your newly created SAML app.
7. Click **User access** and select either **On for everyone** or **Off for everyone** based on your organization's needs.
8. Once done, hit **Save** to finish the configuration process.
***
### Configuration in GitProtect
1. Login to your XMS web panel, go to **Settings** (bottom-left corner in the left-hand side menu) and select **External Identity Providers**.
2. Click **Add new provider** button and fill in the details:
> **Name:** your own custom name, i.e., **Google**
>
> **Entity ID:** should be the same name you've set in Google (in this example it's **SAMLGOOGLE**)
3. Next, paste the previously copied metadata URL in the **Metadata URL** field.
4. Add certificate and password if required.
5. Set up a default **Language** and **Role** for the users with **Google** **SAML** authentication permissions.
6. Click **Save** to finish the setup. You can now log out and test your configured **SAML** login integration.
{% endtab %}
{% tab title="JumpCloud" %}
### Configuration in JumpCloud
1. Log in to the **JumpCloud Admin Portal**, navigate to **USER AUTHENTICATION** > **SSO Applications**, and then click **+ Add New Application**.
2. In **Create New Application Integration** window search for **Custom Application**, select it, and hit **Next**.
3. Check **Manage Single Sign-On (SSO)** checkbox and select **Configure SSO with SAML** option., then hit **Next**.
4. In **Enter general info** set a unique custom application name (in this example we'll be using **XONE**), type it in **Display Label** field, and click **Save Application**.
5. In your new application settings go to **SSO** tab and fill the fields as follows:
> **IdP Entity ID:** your unique application name (in this example it's **XONE**)
>
> **SP Entity ID:** your unique application name (in this example it's **XONE**)
6. Click the **Copy Metadata URL** button under **JumpCloud Metadata** at the top and save it for later— it will be needed for **GitProtect** configuration in **XMS**.
7. Scroll down, set **SAMLSubject NameID** to **email**, and for **SAML Subject NameID Format** select **urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress** from the drop down menu.
{% hint style="warning" %}
The **Signature Algorithm** by default is `RSA-SHA256`— leave it as is.
{% endhint %}
8. In **Sign** section select **Assertion**. The IDP URL should read:
>
{% hint style="danger" %}
If you also want to login to GitProtect from the JumpCloud panel, additionally, add your **XoperoONEManagementServiceURL** in **Login URL** field.
{% endhint %}
Correctly filled Login URL example.
9. In **Attributes** section add a new logout response by filling the fields as follows:
> **Service Provider Attribute Name:**
>
> ****/auth/SAMLLogoutResponse
>
> **JumpCloud Attribute Name:** select **email** from the drop-down menu
{% hint style="warning" %}
In the above address, change **GitProtectManagementServiceURL** to your unique **Management Service** URL. You can find it in your login URL— it's the first part of the address (i.e., in ******/authorization/login** the part highlighted in **red** is the URL you need to copy).
{% endhint %}
10. Click **Save** to update the connector and move to the **User Groups** tab. Select the groups/users you want to enable JumpCloud SAML authorization for GitProtect login to.
11. Double-check if the data you entered is correct and save your configuration.
***
### Configuration in GitProtect
1. Login to your **Management Service** web panel, go to **Settings** (bottom-left corner in the left-hand side menu) and select **External Identity Providers**.
2. Click **Add new provider** button and fill in the details:
> **Name:** your own custom name, i.e., **JumpCloud**
>
> **Entity ID:** should be the same name you've set in **SSO IDP Entity ID** in **JumpCloud** (in this example it's **XONE**)
3. Next, paste the previously copied **Metadata URL** in the **Metadata URL** field.
4. Add certificate and password if required.
5. Set up a default **Language** and **Role** for the users with **JumpCloud** **SAML** authentication permissions.
6. Click **Save** to finish the setup. You can now log out and test your configured **SAML** login integration.
{% endtab %}
{% tab title="Okta" %}
### Requirements and limitations
**PKCS #12** file with **X.509** certificate and private key (usually a .pfx file; can be password protected) **must be included** in IdP configuration in **GitProtect**. **X.509** certificate file (usually a .crt file) for signature verification on IdP side **must be included** in application configuration defined in **Okta** panel.
Both files contain the same certificate. The **PKCS #12** file also contains a private key to this certificate.
{% hint style="warning" %}
If the **PKCS #12** file is password protected, add this password to the IdP configuration in **GitProtect** web panel.
{% endhint %}
***
### Configuration in Okta
1. In **Admin** dashboard (in the right-top corner of the window) expand the **Applications** tab and select the **Applications** option.
2. Hit **Create App Integration** button and select **SAML 2.0**.
3. In **General Settings** enter a unique application name and move to **Configure SAML** section.
4. In **Configure SAML** tab set the **Single sign-on URL** parameter as follows:
> ****/Auth/AssertionConsumerService
{% hint style="warning" %}
In the above address, change **GitProtectManagementServiceURL** to your unique **Management Service** URL. You can find it in your login URL— it's the first part of the address (i.e., in ******/authorization/login** the part highlighted in **red** is the URL you need to copy).
{% endhint %}
5. In **Audience URL** type your unique application name that you've previously set in **General Settings** tab.
6. Click **Show advanced settings** and upload the certificate file to **Signature Certificate** field. Check **Allow application to initiate Single Logout** checkbox in the **Enable Single Logout** section— **it's necessary**.
7. You will now see two additional fields under **Enable Single Logout**— fill them as follows:
> **Single Logout URL:**
>
> ****/auth/SAMLLogoutResponse
>
> **SP Issuer:** your unique application name that you've previously set in **General Settings** tab (in this example it's **MyOktaApp**)
{% hint style="warning" %}
In the above address, change **GitProtectManagementServiceURL** to your unique **Management Service** URL. You can find it in your login URL— it's the first part of the address (i.e., in ******/authorization/login** the part highlighted in **red** is the URL you need to copy).
{% endhint %}
8. Next, go to **Group Attribute Statements** section and fill it as follows:
> **Name:** xoperogroup
>
> **Starts with:** XONE
9. Double-check if the data you've entered is correct and click **Next**. In the next window select **I'm an Okta customer adding an internal app** option*,* then hit **Finish**.
10. Open the created application and go to **Sign On** tab.
11. In **SAML Signing Certificates** section select your uploaded certificate and click **Actions** > **View IdP metadata**. Copy the URL of the opened page— it will be required later in **GitProtect** configuration.
12. Once done, go to the **Assignments** tab.
Assignments tab view.
13. Assign the application to a selected user, or group. Hit **Done** to finish the configuration.
***
### Configuration in GitProtect
1. Login to your **Management Service** web panel, go to **Settings** (bottom-left corner in the left-hand side menu) and select **External Identity Providers**.
2. Click **Add new provider** button and fill in the details:
> **Name:** your own custom name, i.e., **Okta**
>
> **Entity ID:** should be the same name you've set in **General Settings** in Okta (in this example it's **MyOktaApp**)
3. Next, paste the previously copied **IdP metadata URL** in the **Metadata URL** field.
4. Add the required **certificate** and a **password** to the **Password Manager**.
{% hint style="info" %}
You can read more about adding a new password to the **Password Manager** in [Adding a new password](https://github.com/axurban/kb_gitprot/blob/kb_gitprot_en/login-and-password/security-assertion-markup-language-saml/broken-reference/README.md) KB article.
{% endhint %}
5. Set up a default **Language** and **Role** for the users with **Okta SAML** authentication permissions.
{% hint style="info" %}
Learn more about roles in [Roles and permissions](https://helpcenter.gitprotect.io/management/user-accounts/roles-and-permissions) KB article.
{% endhint %}
6. Click **Save** to finish the setup. You can now log out and test your configured **SAML** login integration.
{% endtab %}
{% tab title="OneLogin" %}
### Configuration in OneLogin
1. Login to your **OneLogin** admin console and go to **Applications** > **Applications** > **Add App**.
2. Search for **SAML Custom Connector (Advanced)** and select the first result from the search results.
3. Next, enter a unique, custom name for the app in **Display Name** field and hit **Save**.
4. Open the **Configuration** settings of your custom app, fill the displayed fields as follows and hit **Save** to save the configuration:
> **Audience (EntityID):** a unique, custom name to identify the app on the IdP side (in this example we'll be using **XOPEROSAML**)
>
> **ACS (Consumer) URL Validator\*:**
>
> ****/Auth/AssertionConsumerService
>
> **ACS (Consumer) URL\*:**
>
> ****/Auth/AssertionConsumerService
>
> **Single Logout URL:**
>
> ****/auth/SAMLLogoutResponse
{% hint style="warning" %}
In the above address, change **GitProtectManagementServiceURL** to your unique **Management Service** URL. You can find it in your login URL— it's the first part of the address (i.e., in ******/authorization/login** the part highlighted in **red** is the URL you need to copy).
{% endhint %}
5. Click the **SSO** menu option on the left. Change **SAML Signature Algorithm** to **SHA-256**. Copy the **Issuer URL** value and save it for later— it will be needed for **GitProtect** configuration.
{% hint style="warning" %}
To properly configure logout, the private key of the entity that receives the logout request is **required**. You **must** upload a file with the .pfx extension to **GitProtect** for **OneLogin** integration to work properly. Unfortunately, the .pfx file cannot be downloaded directly from **OneLogin**— you have to use your own certificate or generate it for implementation.
{% endhint %}
{% hint style="success" %}
**OneLogin** offers a form where you can generate a self-signed certificate:
{% endhint %}
6. Save all your settings. Open **Users** settings in the left-hand side menu, select user(s) you want to have permission to use **OneLogin** for **GitProtect** authentication, then in the window that pops-up, check the **Allow user to sign in** checkbox and hit **Save**.
{% hint style="danger" %}
Manually edited login details **always** override those set by rules or with provisioned attributes.
{% endhint %}
7. In the **Applications** tab, use the **(+)** button to add proper permissions to your custom application.
***
### Configuration in GitProtect
1. Login to your **Management Service** web panel, go to **Settings** (bottom-left corner in the left-hand side menu) and select **External Identity Providers**.
2. Click **Add new provider** button and fill in the details:
> **Name:** your own custom name, i.e., **OneLogin**
>
> **Entity ID:** should be the same name you've set in **Configuration** (**Audience (EntityID)**) in OneLogin (in this example it's **XOPEROSAML**)
3. Next, paste the previously copied **Issuer URL** in the **Metadata URL** field.
4. Upload the previously downloaded **OneLogin** .pfx certificate file and add a password to it if required.
5. Set up a default **Language** and **Role** for the users with **OneLogin** **SAML** authentication permissions.
6. Click **Save** to finish the setup. You can now log out and test your configured **SAML** login integration.
{% hint style="warning" %}
It's important to understand that with this integration method, you **cannot** initiate the login from the **OneLogin** application page. Instead, the login **must always** be triggered directly from the **GitProtect** side.
{% endhint %}
***
### Group mapping
{% hint style="success" %}
You can use group mapping if you have many users whom you want to assign different permissions to.
{% endhint %}
{% hint style="danger" %}
Each new login to **GitProtect** resets permissions to default— if you change permissions for a user it will only apply **during the active session**. Relogging the user will make permissions return to default.
{% endhint %}
{% hint style="warning" %}
Group mapping configuration **must** be done both in **OneLogin** and **GitProtect**— start by configuring the **OneLogin** side.
{% endhint %}
1. Go to **User** > **Roles** and create roles you would like to use (i.e., **XONE viewers**, **XONE admins**, etc.). Assign these roles to different users.
2. Next, in **Applications** tab, edit the SAML application. Go to **Parameters** and use the **(+)** icon to create a new parameter. In **Name** field enter . Check both **Flags** (**Include in SAML assertion** and **Multi-value parameter**) and save your settings.
3. In **Default if no value selected** section select **User Roles** and **Semicolon Delimited input (Multi-value output)** from the drop-down menu, and save the parameter.
4. In your **GitProtect** console go to ⚙️ **Settings** > **External Identity Providers** and select the IdP you want to edit.
5. Click the **Group mapping** button in the bottom left. In **Claim type** field enter , and in **Claim value** field enter the name of the role, e.g., **XONE viewers**. Select roles and permissions you want this group to have, then save. Repeat this step for each role/permission you want to create.
{% endtab %}
{% endtabs %}
***
## Using IdP authentication method
To log in to **GitProtect** using a SAML-integrated identity provider, always start from the **GitProtect** panel. Do not log in from the IdP panel (for example, the **Okta** panel) to the application configured for **GitProtect** — the only exception is **JumpCloud**, which provides a built-in option to log in directly from its panel.
To enable an existing **GitProtect** user to log in via an identity provider (IdP), you must turn on the IdP login toggle for that account (⚙️ **Settings** > **Accounts** > **Edit**). Once an account is set to use an identity provider (IdP) for authentication, it cannot be switched back. To change the authentication method, **you must delete the account and add it again**.
{% hint style="danger" %}
Enabling IdP login for the root admin account will prevent logging into the system when an external provider is unavailable.
{% endhint %}
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
