docs.us2.ai

DRAFT · Not approved for release

Single Sign-On (SSO) Setup

Us2.ai can achieve Single Sign-on (SSO) using SAML/OIDC for cloud, only SAML for onprem.

1.1 Setting up the Identity Provider (IdP)

💡
This is done by the external party (in Us2’s case, we do it with jumpcloud)

1.1.1 Cloud (AWS Cognito SAML Setup)

  1. Provide the following xml file (for our production cognito) to external party to upload and auto populate some information for their SSO application setup or we could provide our cognito information manually

Guideline

SP Initiated SAML
- IdP Entity ID: (Up to the external party)
- SP Entity ID: Us2.ai Cognito SP (Up to the external party)
- ACS URL: https://us2-ai.auth.us-east-1.amazoncognito.com/saml2/idpresponse
- SAMLSubject's NameID: email
- SAMLSubject's NameID Format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
- Sign assertion: Yes
- Sign authenication request: No
- Login URL: https://us2-ai.auth.us-east-1.amazoncognito.com/oauth2/authorize?response_type=code&client_id=gd0bshntfuoa8c56tkjrjrsb0&redirect_uri=https://app.us2.ai/&identity_provider=<IdP-Entity-ID> 
	(<IdP-Entity-ID> in this url is different than the one set by external party, this is the name we set in cognito page, make sure <IdP-Entity-ID> here is set to be the same as their Us2 Subscription name or put this name under their subscription SSO Provider settings)
- Attribute Mapping
  - `email` to `email` (change it based on external party setup)

Note: Setup above is for SAML. Cognito also supports other type of SSO setup such as OIDC if needed.

1.1.2 Cloud (AWS Cognito OIDC Setup)

  1. External party has to create a OIDC sso application with the following details
    1. Callback URL/Redirect URL: https://us2-ai.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
    2. Sign-out URLs (optional)
      1. https://app.us2.ai/
      2. https://latest-app.us2.ai/
    3. Grant Types: Authorization Code
    4. Client Authentication Type: Client Secret Post
    5. Login URL: https://us2-ai.auth.us-east-1.amazoncognito.com/oauth2/authorize?response_type=code&client_id=gd0bshntfuoa8c56tkjrjrsb0&redirect_uri=https://app.us2.ai/&identity_provider=<IdP-Entity-ID>
      • <IdP-Entity-ID> in this url is different than the one set by external party, make sure <IdP-Entity-ID> here is set to be the same as their Us2 Subscription name
    6. attribute mapping
      1. email
      2. tenant or role (optional)
  2. or if external party is using AWS Cognito, do the following
    1. Create a new app client on their cognito with the above callback URL and Sign-out URLs (optional)

1.1.3 On-prem (SAML)

On SAML Idp such as JumpCloud, Azure AD etc, create an SAML application with the following details, example below in JumpCloud

  1. Upload service provider metadata below to auto populate some of the fields (this xml file assumes the domain is internal-app).

    or manually enter the following

  2. IdP Entity ID: jumpcloud/Us2.ai/onprem/internal-app
  3. Login URL: https://internal-app.us2.ai/api/users/saml2/login/?idp=jumpcloud/Us2.ai/onprem/internal-app
  4. Check "Declare Redirect Endpoint"
  5. Attribute mapping
    1. email to email
  6. Copy the metadata url or export metadata file. (Prefer url option if available as any changes made will be captured dynamically)

Guideline

- IdP Entity ID: <idp-provider> (specified by client, e.g. for azure AD: https://sts.windows.net/97ae560d-1c88-4249-9915-182abdb40198/)
- SP Entity ID: https://<backend-url>/users/saml2/metadata/
- ACS URL: https://<backend-url>/users/saml2/acs/
- SAMLSubject's NameID: email
- SAMLSubject's NameID Format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
- Signature Algorithm: RSA-SHA256
- Sign assertion: Yes
- Sign authenication request: No
- Default RelayState: keep empty
- Login URL: https://<backend-url>/users/saml2/login/?idp=<IdP-Entity-ID>
- Declare Redirect Endpoint: check the box
- Attribute Mapping
  - `email` to `email` (change it based on external party setup)
	- `username` to `username` (optional, username will be derived from email attribute if not provided)

1.2 Setting up the Service Provider (SP)

💡
This is done on Us2’s end

1.2.1 On-prem

  1. Update .env to change authMode to local
    US2_AWS_MODE=local
  2. Update user_profile.py with the exported metadata. Please use at least one of the option below, local for downloaded metadata file, remote for the metadata url.
    # if not updated in .env
US2_AWS_MODE="local"

# if custom domain is used
# US2_SAML_DOMAIN="some-customer-domain.com"

US2_SAML_PROVIDERS = {
		# Changed to customer name here (will be used to lookup for subscription on version 2.3.0 onwards)
    'us2.ai': {
		    # Identity Provider Name (check metadata provided by user and replace it here, used for subscription lookup too if subscription name doesn't match above)
        # Optional in latest build (automatically populated from metadata)
        #'entityid': [
        #    'jumpcloud/Us2.ai/onprem/localhost',
        #    'jumpcloud/Us2.ai/onprem/internal-app',
        #],
        'metadata': {
            'local': [
                # {"url": BASEDIR / 'remote_metadata.xml', 'identifier': 'us2.ai'}
            ],
            'remote': [
                # Us2.ai JumpCloud metadata Url for localhost:5000
                {"url": "https://sso.jumpcloud.com/saml2/metadata/684a74f561c372c957ebd7c2", "identifier": "us2.ai",},
                # Us2.ai JumpCloud metadata Url for internal-app
                {"url": "https://console.jumpcloud.com/saml2/metadata/63f300e5dcffa17f9f09a93b"},
            ],
            'mdq': [
                # {"url": "https://ds.testunical.it","cert": "certficates/others/ds.testunical.it.cert",}, # noqa
            ],
        },
    },
}

# Optional in latest build (automatically populated from metadata and US2_SAML_PROVIDERS )
# Update IDP_IDENTIFIERS for auto redirection to SSO identity provider based on email domain
# <Email domain> to <Identity provider> mapping
# US2_SAML_IDP_IDENTIFIERS = {
#	"us2.ai": "jumpcloud/Us2.ai/onprem/localhost",
#}

# Override this if want to map other attributes to 'sso_groups'
# Default is using Azure AD Groups
# EXTRA_ATTRIBUTE_MAPPINGS: dict[str, tuple[str, ...]] = {
#   'http://schemas.microsoft.com/ws/2008/06/identity/claims/groups': ('sso_groups',),
#}
  3. Subscription lookup.
    1. On admin page, click on edit subscription, Input the provider name and/or groups (if wanted to match against user.sso_groups)

      OR

    2. Make sure subscription is created before user login from the SSO.

      Note: Provider here can be customer_name in the US2_SAML_PROVIDERS (v2.3.0 onwards) or entity_id

      # will try to match Subscription name in this order
# provider is the Identity Provider name
# tenant/role could be pass from Attribute Mapping
- <provider>-<tenant>-<role>
- <provider>-<tenant>
- <provider>
  4. Sample url to access
    https://internal-app.us2.ai/api/users/saml2/login/?idp=jumpcloud/Us2.ai/onprem/internal-app

 

For local testing:

Ensure that xmlsec is available with command xmlsec1 --version. 

- For Ubuntu/WSL, `apt-get install xmlsec1 pkg-config libxml2-dev libxmlsec1-dev libxmlsec1-openssl`
- For Mac, `brew install xmlsec1 libxml2 libxmlsec1 pkg-config`
- For Windows, download all the following binaries listed below from [here](https://www.zlatkovic.com/pub/libxml/64bit/).
  - Download 32bit/64bit version as per your machine.
    - xmlsec
    - libxslt
    - libxml2
    - openssl
    - iconv
    - zlib
    - libtool
  - Copy all content of bin folder of each binaries above into a folder (e.g. C:/bin) and add to environment path.
  - Note that, Windows version of pySAML2 (used by djangosaml2) currently not working fine yet (as of 9/2/2023) due to issue mentioned [here](https://github.com/IdentityPython/pysaml2/pull/665).
- For other OS, refer [here](https://pypi.org/project/xmlsec/).

xmlsec should be readily available in most Linux distributions, else install as follows.

1.2.2 Cloud (AWS Cognito for SAML/OIDC)

  1. Add a new identity provider in Social and external providers
    1. Choose the SAML option or OIDC
      1. SAML
        1. Provider Name: User subscription name
        2. Identifiers: email domain to check against for this provider
        3. Required SP-initiated SAML assertions
        4. Provide metadata document or URL (to be provided by customer)
        5. map attribute
          1. email (update this based on customer mapping) to email
          2. tenant (optional)
          3. role (optional)
      2. OIDC
        1. Provider Name: User subscription name
        2. Identifiers: email domain to check against for this provider
        3. Client ID: <Provided by user>
        4. Client secret: <Provided by user, Optional, can leave it empty>
          # if OIDC provider is using cognito, both Client ID and Client secret and be found under app client. Client secret will be optional, depends on if user generates it or not.
        5. Authorized scopes: openid email
        6. Identifiers: email domain to check against for this provider
        7. Attribute request method: GET
        8. Auto fill
        9. Issuer URL: <Provided by user>
          # if the OIDC provider is using cognito, format as follows
https://cognito-idp.<region>.amazonaws.com/<user_pool_id>

# e.g.
https://cognito-idp.ca-central-1.amazonaws.com/ca-central-1_DL4BGdG6i
        10. Map attributes
          1. email to email
          2. email_verified to email_verified (optional)
          3. tenant (optional)
          4. role (optional)

          Note: sub to username will be automatically mapped by cognito. Their username will be <Provider Name>_<sub>. To set a different username, map a field to preferred_username

  2. In App clients, add the newly created identity provider to the us2 app client
  3. Subscription lookup.
    1. On admin page, click on edit subscription, Input the provider name and/or groups (if wanted to match against user.sso_groups)

      OR

    2. Make sure subscription is created before user login from the SSO.

      Note: Provider here can be customer_name in the US2_SAML_PROVIDERS (v2.3.0 onwards) or entity_id

      # will try to match Subscription name in this order
# provider is the Identity Provider name
# tenant/role could be pass from Attribute Mapping
- <provider>-<tenant>-<role>
- <provider>-<tenant>
- <provider>
  4. Sample url to access
    https://us2-ai.auth.us-east-1.amazoncognito.com/oauth2/authorize?response_type=code&client_id=gd0bshntfuoa8c56tkjrjrsb0&redirect_uri=https://app.us2.ai/&identity_provider=<identity_provider>

# optionally, could append path to state param (which will redirect to that specific path instead)
https://us2-ai.auth.us-east-1.amazoncognito.com/oauth2/authorize?response_type=code&client_id=gd0bshntfuoa8c56tkjrjrsb0&redirect_uri=https://app.us2.ai/&identity_provider=<identity_provider>&state=/us-east-1/search;tags=StudyInstanceUID:1.2.840.113663.1500.1.467288131.1.1.20250123.63612.483//measurement

 

Revision: A

 

RevisionChange DescriptionEdited byRelease DateApproval
AIntial Release. Ported from Internal wiki2025-11-18