# Single Sign On (SAML) Replex’s SAML implementation allows admins to configure SSO authentication using any one of a number of compliant identity providers (IdPs). Admins can configure any IdP that conforms to the SAML form of authentication, to be used with Replex. These include but are not limited to the following IdPs: * Okta * OneLogin * Azure Active Directory * SecureAuth * TrustBuilder * adAS * ADFS ### Add SAML Integration To configure SAML, click on **Settings** in the left hand panel and then click on **Single Sign On (SAML)**. If you are configuring SAML for the first time you will see a screen with no entries. To add your first SAML integration click on **+ Add SAML Integration** in the top right corner. On the next screen, enter the **Name** and **Provider** of your SAML integration. ![Integrating Single Sign On (SAML)](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MR4ezBYNxQLEp4tufWB%2F-MR4fLb3ZSdVMjksDVrQ%2Fokta-11-New-SAML-Integration-Replex.png?alt=media\&token=63cfebb6-9b45-4186-8983-70909e14a94d) To proceed follow one of the two implementation methods: manual or automatic setup. #### Automatic Setup The automatic setup allows admins to easily integrate SAML by exchanging configuration metadata with the IdP. {% hint style="info" %} Automatic setup is only supported by some IdPs. {% endhint %} Follow the steps outlined below to integrate SAML using the automatic setup method: 1. Download the **Configuration Metadata** using the button right at the start of the Automatic setup section. 2. Upload the metadata file downloaded in the previous step to your IdP. 3. Download the **IdP-metadata** file issued from your IdP or note the ssoLink and the certificate provided by the IdP to sign SAML messages. 4. To complete the integration, upload the IdP-metadata file downloaded in the previous step in the **IdP Metadata** section right at the end of the screen. Make sure you choose **File**, before uploading the IdP-metadata file. 5. Integration can also be completed by choosing **Manual Input** in the **IdP Metadata** section and entering the ssoLink and signing certificate noted in step 3. #### Manual Setup To complete the integration using the manual method follow the steps below: 1. Create a SAML app in your IdP. During the SAML app creation you will need to provide the following four values to your IdP (copy these values using the button in front of each field and paste them into your IdP): * ACS URL * Logout URL * Audience/SP Entity ID * Name ID Format 2. Download the **IdP-metadata** file issued from your IdP or note the ssoLink and the certificate provided by the IdP to sign SAML messages. 3. To complete the integration, upload the IdP-metadata file downloaded in the previous step in the **IdP Metadata** section right at the end of the screen. Make sure you choose **File**, before uploading the IdP-metadata file. 4. Integration can also be completed by choosing **Manual Input** in the **IdP Metadata** section and entering the ssoLink and signing certificate noted in step 2. ![Manual Setup](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MR5JLtHsPX499ix2fUY%2F-MR5JzFGgCtd-W78oJlz%2F1-sso-New-SAML-Integration-Replex.png?alt=media\&token=7de67024-ed23-4871-bd7e-15e1ec8e5eeb) ### Edit or Remove Integration Admins can edit previously added **SAML Integrations** by clicking the edit icon in front of each integration. ![Edit SAML Integration](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MR56Pq-YuTnkU-m3qv1%2F-MR57k09FgWBIaxNZg8q%2Fokta-21-Edit-SAML-Integration-Replex.png?alt=media\&token=9fcfd153-a6f3-42f5-bb30-516d3c310fb9) Previously added **SAML Integrations** can be deleted by clicking on the delete icon in front of each integration. ### Okta Integration In this section of the documentation, we will provide a detailed walkthrough of integrating Okta with Replex. Since Okta does not provide a way to upload configuration metadata from the service provider, we will be following the manual method of SAML integration. {% hint style="info" %} You will require an account with administrator privileges in Okta to complete the integration {% endhint %} Navigate to the **Single Sign On (SAML)** screen by clicking on **Settings** in the left hand panel of the Replex UI. Once there, enter the **Name** and **Provider** of the SAML implementation. Here we use "Okta SSO" as the **Name** and "Okta" as the **Provider**. Download the **Configuration Metadata** file. ![Enter Name and Provider](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MR4ifhdakbV-hnd0Rpp%2F-MR4ivj8v2ZVRE4WqufI%2Fokta-11-New-SAML-Integration-Replex.png?alt=media\&token=553b7727-5b07-474f-afa3-9b9891f7bbf6) #### Create SAML App in Okta Open Okta in your browser and sign in using an account with administrator privileges. Navigate to **Applications**. ![Okta Applications](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-Mfs4GF7g4PIFaAzk5A0%2F-Mfs5SepPXmYTcI8mkha%2Fokta-dev-37030484-Applications.png?alt=media\&token=71d50349-8d3e-4ec6-bdb5-8363ae9c65f1) Click **Create App Integration**. In the **Create a new app integration** pop-up, choose **Saml 2.0** as the sign-in method and click **Next.** ![Choose sign-in method](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-Mfs4GF7g4PIFaAzk5A0%2F-Mfs6LhdFbj2Jn0nAi9Z%2Fokta-dev-37030484-Applications%20\(1\).png?alt=media\&token=1de0aab4-1ee2-490b-9d7d-a10f6712c116) This will open the **Create SAML Integration** Wizard, which will guide you through the process of creating a new app in Okta. In the **General Settings** tab, enter **Replex** as the **App Name** and optionally upload the Replex logo. You can also choose whether to display the application icon, in the **App visibility** section. ![General Settings Tab](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-Mfs6htGbJT9Muibn51o%2F-Mfs7c7h9z3xrc2QQYEI%2Fokta-dev-37030484-Applications%20\(2\).png?alt=media\&token=f95ef5a9-988a-4c9b-ac46-a5e710329dab) Click **Next** to proceed. In the **Configure SAML** tab, copy and paste the **ACS URL** from the Replex UI into the **Single sign on URL** field. Similarly, copy and paste the **Audience/SP Entity ID** from the Replex UI into the **Audience URI (SP Entity ID)** field. Next choose **EmailAddress** from the drop down list in front of the **Name ID format** field. Similarly, choose **Email** from the drop down in front of the **Application username** field. Next choose **EmailAddress** from the drop down list in front of the **Name ID format** field. Similarly, choose **Email** from the drop down in front of the **Application username** field. ![Configure SAML](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-Mg54LcYV5hhLMG0tLoN%2F-Mg5L60yeQVGBaVstNi7%2Fokta-dev-37030484-Applications%20\(3\).png?alt=media\&token=df842f8c-7520-4262-9a2c-f3f3639f6569) Click **Show Advanced Settings** and set the **Assertion Encryption** to **Encrypted**. Create a file **sp\_certificate.pem**, open the previously downloaded sp metadata xml file and copy the encryption certificate. Paste the encryption certificate into the new .pem file replacing {ENCRYPTION\_CERTIFICATE}. ``` -----BEGIN CERTIFICATE----- {ENCRYPTION_CERTIFICATE} -----END CERTIFICATE----- ``` Upload **sp\_certificate.pem** file in the **Encryption Certificate** field. ![](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MfrBueLYdwpUVpig4HL%2F-MfrLaay6JW0qiiPJE9v%2FScreenshot%202021-07-30%20at%2015.18.31.png?alt=media\&token=f1aa1a54-ef66-4c1e-aab8-9c1b833a5f43) You can verify the information entered above by scrolling down to Section B and clicking on **Preview the SAML Assertion** button. ![Preview the SAML Assertion](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MgAVRxaSblbKB3FTrGA%2F-MgAVY_r267Lp4PPb8rN%2Fokta-dev-37030484-Applications%20\(4\).png?alt=media\&token=5286d025-ae8e-42f7-a2bf-40a13aa77da9) Click **Next** to proceed. Fill out the required **Feedback** tab and click **Finish**. This will create the new Okta application and you will be redirected to the **Sign On** tab of the newly created application overview screen. Download the **identity provider metadata** file at the bottom of the screen. ![](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MgAVueZSM89HZRVfi3y%2F-MgAWfUWQvfWOBGt2lAc%2Fokta-dev-37030484-replex-replex.png?alt=media\&token=a37d81a3-13bd-42bf-97df-dd604d9c24f1) #### Upload Configuration file to Replex Switch to the Replex UI and upload the **identity provider metadata** file downloaded in the previous step in the **IdP Metadata** section. Next click on **Save** to complete the setup and activate the Okta integration. ![Upload identity provider metadata file](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MR4kWjft4nt1JLXvMN7%2F-MR4lRbFhyAHBoi0wbah%2Fokta-12-New-SAML-Integration-Replex.png?alt=media\&token=de63d25b-6733-4b37-9615-2b59b0bf02de) To enable users to access Replex via Okta, they have to get it assigned to them first. To do this, navigate to the **Assignments** tab of the **Applications** view in your Okta account, click on **Assign** to assign Okta to either people to groups. ![Assign to People or Groups](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MgAVueZSM89HZRVfi3y%2F-MgAXy-BOkvRm9hmY3Ey%2Fokta-dev-37030484-replex-replex%20\(1\).png?alt=media\&token=4cc36970-1186-4583-bb39-f34e7813a939) Each new user assigned will have the **User** role assigned to them when first logging in. In the Replex UI admins can review the new Okta integration in the **Single Sign On (SAML)** section of the **Settings** Page. They can also edit or delete the integration using the respective icons in front of the integration. ![Review, edit, delete SAML integrations](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MR4kWjft4nt1JLXvMN7%2F-MR4m5r7UjlcyokQjOrG%2Fokta-10-Single-Sign-On-SAML-Replex.png?alt=media\&token=9c0b484e-1ce5-4348-ae65-36522e343ab4) ### Keycloak Integration In this section of the documentation, we will provide a detailed walkthrough of integrating Keycloak with Replex. {% hint style="info" %} You will require an account with administrator privileges in Keycloak to complete the integration {% endhint %} Navigate to the **Single Sign On (SAML)** screen by clicking on **Settings** in the left hand panel of the Replex UI. Once there, enter the **Name** and **Provider** of the SAML implementation. Here we use "Keycloak SSO" as the Name and "Keycloak" as the Provider. ![Enter Name and Provider](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MT_Cft17Y0R3YlToCsA%2F-MT_hud2F8bfx12caH_p%2Fk8s_101_New-SAML-Integration-Replex.png?alt=media\&token=65fd2537-5636-43e3-ab6a-813057549712) Download the configuration metadata file using the green **Configuration Metadata** download button. Now switch to the Keycloak UI and create a new Realm for Replex. ![Create new Keycloak realm](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MT_p6pMMCz9PXkhg9L9%2F-MT_paklZ2Y-ZmDaLNwq%2Fk8s_110_Keycloak-Admin-Console.png?alt=media\&token=20ffa237-ac0d-42c3-bdd6-bff5535b3464) Next create a SAML client in Keycloak by navigating to the **Clients** section of the **Configure Realm** panel and click on create in the top right corner. ![Create SAML Client](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MTpUGY_wYhDCI7EEv9y%2F-MTpUZXmxhBMCE5VAvfL%2Fk8s_103_Keycloak-Admin-Console.png?alt=media\&token=24573d5a-eb44-4c08-96b1-aa223c5e67cb) In the next screen, click on **Select File** and choose the **Configuration Metadata** file downloaded from the Replex UI. ![Upload Medata File](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MTpUGY_wYhDCI7EEv9y%2F-MTpUhUFVG2P4n1bkGgn%2Fk8s_104_Keycloak-Admin-Console.png?alt=media\&token=f8049133-fc96-41ed-86f7-e404e4505f95) The form fields will populate automatically, once the file has been selected. Click **Save**. Make sure that the "Client Signature Required" switch is disabled. {% hint style="info" %} To ensure that the replex profile is complete, it is recommended to map users personal info (like first and last name) to saml responses. To do this, open the “Mappers” section and click “Add Builtin”. In the “Add” column select “X500 givenName” and “X500 surname” rows and click “Add selected”. This data can also be provided in custom user properties mappers under “firstName” and “lastName” SAML attributes. {% endhint %} Click **Save** again at the bottom of the page. ![](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MTpUGY_wYhDCI7EEv9y%2F-MTpUol7CAXqxBCmfN93%2Fk8s_105_Keycloak-Admin-Console.png?alt=media\&token=d1532fe7-c84a-412b-849a-0dd81d7da092) Click on Settings in the **Configure Realm** panel and navigate to the **General** tab. Click on the SAML 2.0 Identity Provider Metadata link and save the file as idp\_metadata.xml. ![](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MTpUGY_wYhDCI7EEv9y%2F-MTpUuQE_9BUvyi5U7X0%2Fk8s_106_Keycloak-Admin-Console.png?alt=media\&token=832a2d7d-d277-4770-a2c2-6c68376f6114) Switch to the **Add SAML** **Integration** section of the Replex UI and scroll down to the IdP Metadata section. Upload the previously saved idp\_metadata.xml file and click save. ![](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MTpV33xPX46zMBapoqF%2F-MTpV5ZWlurs4-wnnY1o%2Fk8s_107_New-SAML-Integration-Replex.png?alt=media\&token=e6dc7d16-0593-4dae-86af-e22b4e8a57e5) This will activate the keycloak integration. To enable users to access Replex via Keycloak, add users by navigating to the **Users** section of the **Manage Realm** panel in Keycloak. ![Add Users to Keycloak](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MTvLIAZhlCuvVGWVLxG%2F-MTvNFkfivZrgBRKQzlW%2Fk8s_118_Keycloak-Admin-Console.png?alt=media\&token=d71aba24-c53b-4be7-ab9a-a408a47e9d44) ![Add Users to Keycloak](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MTvLIAZhlCuvVGWVLxG%2F-MTvMvz6i2rpEsHK9rkd%2Fk8s_117_Keycloak-Admin-Console.png?alt=media\&token=c386f556-4385-4bea-99e2-d156d5cf65ea) In the Replex UI admins can review the new Keycloak integration in the **Single Sign On (SAML)** section of the **Settings** Page. They can also edit or delete the integration using the respective icons in front of the integration. ![Review Keycloak Integration](https://4068579783-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGA2pJIFrMdGZ5i84m%2F-MTvNaM1PlUmd49KO6k-%2F-MTvNmBFFHHXqzh8MxFu%2Fk8s_119_Single-Sign-On-SAML-Replex.png?alt=media\&token=f0d655d9-5a49-4290-b3d6-11a9cf9fbb99) ### **On-Prem installation** For on-prem installations the following environment variables are required to make SAML auth work properly:‌ * SAML\_DECRYPTION\_PRIVATE\_KEY * SAML\_DECRYPTION\_PUBLIC\_CERT * SAML\_SIGNING\_PRIVATE\_KEY * SAML\_SIGNING\_PUBLIC\_CERT‌ These variables are used to generate Service Provider metadata and to sign SAML requests.‌ `SAML_DECRYPTION_PRIVATE_KEY` and `SAML_DECRYPTION_PUBLIC_CERT` are used to share encrypted SAML messages. In most cases encryption is not used, but in cases where it is needed these two variables take in place. During the SAML setup, the IdP receives Public Cert (from SP Metadata) so it can encrypt SAML message with it, and then on SP side ‌it could be decrypted using Private Key. \ `SAML_DECRYPTION_PRIVATE_KEY` is a rsa sha256 private key.‌\ `SAML_DECRYPTION_PUBLIC_CERT` is a pair to the private key in x509 certificate format.‌ `SAML_SIGNING_PRIVATE_KEY` and `SAML_SIGNING_PUBLIC_CERT` are used to share signed SAML Authentication requests to the IdP. This is a common practice to provide trusted info about the issuer of the request (SP). \ `SAML_SIGNING_PRIVATE_KEY` is a rsa sha256 private key.‌\ `SAML_SIGNING_PUBLIC_CERT` is a pair to the private key in x509 certificate format.‌ First of all, the keys must be generated, e.g. using an openssl cli util:\ \ \&#xNAN;*For decryption:*\ `openssl req -x509 -nodes -sha256 -days 3650 -newkey rsa:2048 -keyout decryption_private_key.pem -out decryption_public_certificate.pem`*For encryption:*`openssl req -x509 -nodes -sha256 -days 3650 -newkey rsa:2048 -keyout signing_private_key.pem -out signing_public_certificate.pem`‌ These two commands will create 4 files: * decryption\_private\_key.pem * decryption\_public\_certificate.pem * signing\_private\_key.pem * signing\_public\_certificate.pem Next step is to encode previously generated keys with base64 encoding. Following cli command can be used:‌ `base64 -w 0 {KEY_NAME}.pem`‌, where `KEY_NAME` is name of the key generated in the previous step.\ After encoding the 4 base64 encoded strings should be generated.\ Example:\ `>>> base64 -w 0 decryption_private_key.pem`\ `>>> LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2UUlCQURBTkJn...` Lastly update or create secrets file `server-secret.yaml` to add these values.\ If file was not created before, create it, and add following values from `data` so the final secrets file wil look like: \ `apiVersion: v1`\ `kind: Secret`\ `metadata:`\ `name: replex-rsa-keys`\ `type: Opaque`\ `data:`\ `signingPrivateKey: `\ `signingPublicCert: `\ `decryptionPrivateKey: `\ `decryptionPublicCert: ` {% hint style="info" %} Make sure that Secret name is the same as the on used in Deployment {% endhint %} Apply the secrets by using `kubectl apply`:\ `kubectl apply -f ./server-secret.yaml -n {REPLEX_SERVER_NS}`, where `REPLEX_SERVER_NS` is the namespace where Replex Server is deployed.