Single Sign On (SAML)
Last updated
Last updated
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
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.
To proceed follow one of the two implementation methods: manual or automatic setup.
The automatic setup allows admins to easily integrate SAML by exchanging configuration metadata with the IdP.
Automatic setup is only supported by some IdPs.
Follow the steps outlined below to integrate SAML using the automatic setup method:
Download the Configuration Metadata using the button right at the start of the Automatic setup section.
Upload the metadata file downloaded in the previous step to your IdP.
Download the IdP-metadata file issued from your IdP or note the ssoLink and the certificate provided by the IdP to sign SAML messages.
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.
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.
To complete the integration using the manual method follow the steps below:
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
Download the IdP-metadata file issued from your IdP or note the ssoLink and the certificate provided by the IdP to sign SAML messages.
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.
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.
Admins can edit previously added SAML Integrations by clicking the edit icon in front of each integration.
Previously added SAML Integrations can be deleted by clicking on the delete icon in front of each 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.
You will require an account with administrator privileges in Okta to complete the integration
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.
Open Okta in your browser and sign in using an account with administrator privileges. Navigate to Applications.
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.
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.
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.
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}.
Upload sp_certificate.pem file in the Encryption Certificate field.
You can verify the information entered above by scrolling down to Section B and clicking on Preview the SAML Assertion button.
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.
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.
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.
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.
In this section of the documentation, we will provide a detailed walkthrough of integrating Keycloak with Replex.
You will require an account with administrator privileges in Keycloak to complete the integration
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.
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.
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.
In the next screen, click on Select File and choose the Configuration Metadata file downloaded from the Replex UI.
The form fields will populate automatically, once the file has been selected.
Click Save.
Make sure that the "Client Signature Required" switch is disabled.
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.
Click Save again at the bottom of the page.
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.
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.
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.
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.
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:
For decryption:
openssl req -x509 -nodes -sha256 -days 3650 -newkey rsa:2048 -keyout decryption_private_key.pem -out decryption_public_certificate.pemFor 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: <BASE64-ENCODED signing_private_key.pem>
signingPublicCert: <BASE64-ENCODED signing_public_certificate.pem>
decryptionPrivateKey: <BASE64-ENCODED decryption_private_key.pem>
decryptionPublicCert: <BASE64-ENCODED decryption_public_certificate.pem>
Make sure that Secret name is the same as the on used in Deployment
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.
