> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minimus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure SSO (Generic Guide)

> Configure single-sign-on (SSO) to Minimus using any SAML 2.0 identity provider

This is a generic guide for configuring SSO. If you are using Google, Azure, or Okta as your identity provider, the specialized guide is recommended:

* [Configure SSO with Azure](/sso/azure)
* [Configure SSO with Google](/sso/google)
* [Configure SSO with Okta](/sso/okta)

## Prepare the SSO form in Minimus

1. Go to **Manage** > **Users & Groups** ([direct link](https://images.minimus.io/manage/access/users?saml=open))
2. Click **Configure SSO** at the top of the page to open the Minimus SSO form.
   <Tip>
     Keep this form open and available in another browser tab as you configure the SAML app in Azure.
   </Tip>
3. The form has 4 parts:
   1. **Configure Minimus as a custom app in your identity provider** - You will copy these parameters from Minimus to your IdP in the next steps.
      1. SP Entity ID
      2. Reply URL (Callback / ACS URL)
      3. Relay State (optional) - If you leave the Relay State blank, users will only be able to login with SSO from the Minimus homepage.
   2. **Connect Minimus to your identity provider** - You will fetch these parameters from your IdP custom app and save them to the Minimus form.
      1. Login SSO URL
      2. IdP Entity ID
      3. Certificate
   3. **SAML Attribute Mapping** - You will match these parameters with the attributes defined in your IdP:
      1. Email
      2. Full name
      3. Group Mapping
   4. **Group Mapping** is optional and can be enabled if you plan to configure user groups. [See the instructions in user groups](https://docs.minimus.io/manage/user-groups).

## Add Minimus as a custom SAML app in your identity provider

<Steps>
  <Step title="Configure Minimus as a custom app in your identity provider">
    The first step is to create a dedicated application for Minimus in your IdP.

    1. Login to the IdP Admin Console. You will need sufficient permissions to manage the SAML applications.
    2. Create a new SAML application and select **SAML 2.0** as the sign-in method.
    3. Name the application. (**Minimus App** is a good example.)

    The exact path for creating the app will depend on your provider.
  </Step>

  <Step title="Configure the custom SAML app">
    1. In another browser window, open your Minimus app and go to **Manage > User Management**. Click **Configure SSO** to open the SSO form (top right corner).
    2. Copy the following parameters from the Minimus app to your IdP.

    | Minimus Parameter             | Examples of parameter naming in IdPs                                  |
    | :---------------------------- | :-------------------------------------------------------------------- |
    | SP Entity ID                  | SP Entity ID, Service Provider ID, Audience URI                       |
    | Reply URL (also Callback URL) | Single sign-on URL, ACS URL, Callback URL, Service Provider Login URL |
    | Relay State                   | Default RelayState                                                    |

    <Warning>
      The order of the parameters can be different in your IdP.  
    </Warning>
  </Step>

  <Step title="Connect the SAML app back to Minimus">
    In this step, we copy the unique parameters from the custom app in the IdP back to the Minimus SSO form. (This is the second section in the Minimus form: **Connect Minimus to your identity provider**).

    Once the custom SAML app is created, it usually lists the unique parameters in a SAML section or tab.

    | Minimus Parameter | Examples of parameter naming in IdPs              | Description                                   |
    | :---------------- | :------------------------------------------------ | --------------------------------------------- |
    | SSO URL           | Sign on URL, Identity provider Single Sign-On URL | The app-specific login URL created by the IdP |
    | Entity ID         | Issuer, Identity Provider Issuer URL or ID        | The IdP's unique identifier or issuer ID      |
  </Step>

  <Step title="Copy the public certificate">
    The IdP's SAML app will usually provide several certificate options. Copy the Base64 public certificate to the certificate field in the Minimus SSO form.

    Open the certificate in notepad or another code viewer, and copy the code. Make sure the certificate includes the opening and closing tags.

    <Warning>
      Sometimes, if you copy the certificate instead of downloading it, it may not include the opening and closing tags:\
      \
      \-----BEGIN CERTIFICATE-----

      \-----END CERTIFICATE----- \
      \
      If so, you can paste the certificate between the tags provided by the placeholder.
    </Warning>
  </Step>

  <Step title="Configure the SAML attribute mapping in Minimus">
    Attribute mapping is necessary to ensure that the values sent from the IdP match Minimus expectations. Many identity providers use the standard schema but some have other formats (See [Okta](/sso/okta) for example).

    | Minimus Attribute | Standard Schema                                                                                                                          |
    | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
    | Email             | [http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress) |
    | Full Name         | [http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name)                 |
  </Step>

  <Step title="Save the Minimus SSO form">
    You are now ready to save the SSO configuration form in Minimus.
  </Step>

  <Step title="Assign access in your IdP">
    Grant IdP groups and/or users access to Minimus. Usually, you will need to add or assign users to the custom SAML app to give them access.
  </Step>
</Steps>

## Troubleshooting SSO access

When copying the certificate to Minimus, make sure there is no whitespace before or after the certificate. Also, check that the expected prefix and suffix are included.

```text theme={null}
-----BEGIN CERTIFICATE-----

-----END CERTIFICATE-----
```