.. include:: /includes.txt ====== SAML 2 ====== Zercurity supports SAML2. Allowing automatic logon form 3rd party identity partners. Create integration ================== From the integration pane under settings. :doc:`/settings/integrations` .. image:: /_static/integrations_saml.png Simply enter your Identity provider's (IDP) name e.g. Okta, Google, Auth0. These providers will also provide your with your IDP metadata file. Which you will need to upload in order to complete your SAML configuration. The IDP metadata file should look similar to the example below: .. code-block:: xml YOUR_IDP_PROVIDER_CERT urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress Generic SAML Configuration ========================== +---------------------+-------------------------------------------------------+ | **Field name** | **Input** | +---------------------+-------------------------------------------------------+ | ACS URL | `https://api.zercurity.com/v1/auth/saml2` | +---------------------+-------------------------------------------------------+ | Entity ID | `https://api.zercurity.com/v1/auth/saml2` | +---------------------+-------------------------------------------------------+ Auth0 SAML Configuration ======================== This will be updated shortly. Google SAML Configuration ========================= Zercurity supports integration with Google's SAML as in identity provider (IDP). To start, logon to your Google Admin portal. https://admin.google.com/ and choose **Apps** from the dashboard. .. image:: /_static/integrations_saml_01.png Then choose **SAML apps**. Then on the next screen using the **plus** icon in the lower right of your browser screen to create your new SSO application for your users. Unfortunately, Google doesn't provide a default configuration for Zercurity, so you'll need to **SETUP MY OWN CUSTOM APP** .. image:: /_static/integrations_saml_02.png Under **Option 2** Download use the download link for your **IDP metadata** file. **Look after this file as you'll need it later to upload directly to Zercurity.** On the next screen enter your application name **Zercurity** and upload an image to identify your Zercurity application to your users. .. image:: /_static/integrations_saml_03.png For your service provider details, both the **ACS URL** and **Entity ID** are as follows: +---------------------+-------------------------------------------------------+ | **Field name** | **Input** | +---------------------+-------------------------------------------------------+ | ACS URL | `https://api.zercurity.com/v1/auth/saml2` | +---------------------+-------------------------------------------------------+ | Entity ID | `https://api.zercurity.com/v1/auth/saml2` | +---------------------+-------------------------------------------------------+ The **Name ID format** must also be set to **EMAIL** .. image:: /_static/integrations_saml_04.png On the last page (which is optional) you'll need to configure some field mappings to help Zercurity correctly populate user information. .. image:: /_static/integrations_saml_05.png Once you're done click **FINISH** and your new SAML app will be listed. You now need to assign the app to specific users or enable it for your organisation. Once you've completed those steps. You can now upload the IDP metadata file to Zercurity via the integration setup wizard under the settings pane within Zercurity. Okta SAML App ============= Zercurity can be added to your Okta dashboard by installing our App via the Okta Integration Network (OIN). https://www.okta.com/integrations/zercurity/ .. image:: /_static/integrations_okta_oin_01.png Installing the Okta App ----------------------- From your Okta account visit the Applications tab and then click **Add application**. Search for **Zercurity** in the search bar and then click on the first result for **Zercurity**. .. image:: /_static/integrations_okta_oin_02.png Once you've located our Okta OIN app. Click the green **Add** button. This will then start the setup process. Simply name your application. **Zercurity** should suffice. .. image:: /_static/integrations_okta_oin_03.png Upon completion, you'll be taken to assign users to the new Application. Add the users you wish to access Zercurity to your new application. Once completed the last step will be to download the `Metadata.xml` from Okta in order to dynamically configure Zercurity's SAML integration. Under the **Sign-on** tab there will be a button called **View Setup Instructions**. .. image:: /_static/integrations_okta_oin_04.png This page will walk you through the last configuration steps. .. image:: /_static/integrations_okta_oin_05.png Okta SAML Configuration ======================= You can use Zercurity's SAML integration to add SSO support for Okta. Login and visit your **applications** page and click **Add new app**. This will open a new dialogue to configure your app. Ensure the platform is set to **Web** and the **Sign on method** is **SAML 2.0** .. image:: /_static/integrations_okta_dev_01.png Click **create** and next you'll need to provide an name for your application and you can also upload an image to use for your application. The other options can remain as default. .. image:: /_static/integrations_okta_dev_02.png Next, is the main configuration section. For both the **Single sign on URL** and **Audience URI (SP Entity ID)** need to be set to: +---------------------+-------------------------------------------------------+ | **Field name** | **Input** | +---------------------+-------------------------------------------------------+ | Single sign on URL | `https://api.zercurity.com/v1/auth/saml2` | +---------------------+-------------------------------------------------------+ | SP Entity ID | `https://api.zercurity.com/v1/auth/saml2` | +---------------------+-------------------------------------------------------+ The **Name ID format** needs to be set to **EmailAddress** and **Application username** needs to be set to **Email** This will be used to map your Okta account to your Zercurity account. .. image:: /_static/integrations_okta_dev_03.png In the event the account isn't already in Zercurity you can set the following optional fields to map your Okta user information across into Zercurity. When a new account is created the user will receive an email from us confirming the account creation. .. image:: /_static/integrations_okta_dev_04.png Lastly, mark the application as an Internal app. .. image:: /_static/integrations_okta_dev_05.png The Zercurity app will now be visible from your Okta dashboard. .. note:: You will need to first assign users to the Zercurity app before it shows up in your user dashboard. .. image:: /_static/integrations_okta_dev_06.png In order to setup Zercurity you will need your IDP metadata file. This can be downloaded from the **Sign on** tab. Click the **View setup instructions** button. .. image:: /_static/integrations_okta_dev_07.png **Scroll to the bottom of the page** and you'll see under optional your IDP metadata file which can be uploaded straight to Zercurity to complete your configuration. .. image:: /_static/integrations_okta_dev_08.png On-prem ======= For the instructions above your SAML ACS and Entity ID need to be updated with your domain name. `https://api.zercurity.com/v1/auth/saml2` becomes `https://api.example.com/v1/auth/saml2`