Skip to content

Latest commit

 

History

History
79 lines (60 loc) · 5.86 KB

SAML.md

File metadata and controls

79 lines (60 loc) · 5.86 KB
Raw

SAML configuration

Configure service and identity providers

Description of configuration:

  • sp-metadata.xml - this is the configuration of service provider (hereinafter SP), made specifically for the Nexus application. The only thing that may be required is to correct "entityID" and "Location" depending on the DNS name and protocol you use, endpoint will always be "/callback?client_name=SAML2Client". Example for DNS myNexusDomain:

    <md:EntityDescriptor ... entityID="http(s)://myNexusDomain/callback?client_name=SAML2Client" validUntil="2042-03-17T05:02:50.999Z">
        ...
    <md:SPSSODescriptor ...>
        <md:Extensions xmlns:init="urn:oasis:names:tc:SAML:profiles:SSO:request-init">
            <init:RequestInitiator ... Location="http(s)://myNexusDomain/callback?client_name=SAML2Client"/>
        </md:Extensions>
        ...
        <md:SingleLogoutService ... Location="http(s)://myNexusDomain/callback?client_name=SAML2Client&amp;logoutendpoint=true"/>
        <md:SingleLogoutService ... Location="http(s)://myNexusDomain/callback?client_name=SAML2Client&amp;logoutendpoint=true"/>
        <md:SingleLogoutService ... Location="http(s)://myNexusDomain/callback?client_name=SAML2Client&amp;logoutendpoint=true"/>
        <md:SingleLogoutService ... Location="http(s)://myNexusDomain/callback?client_name=SAML2Client&amp;logoutendpoint=true"/>
        ...
        <md:AssertionConsumerService ... Location="http(s)://myNexusDomain/callback?client_name=SAML2Client" index="0"/>
    </md:SPSSODescriptor>
</md:EntityDescriptor>

  • The value of the attribute "entityID" in sp-metadata.xml should be the same as the attribute "serviceProviderEntityId" and "callbackUrl" in shiro.ini (also depending on the DNS name you use), ex:

    # Same as the attribute entityID
saml2Config.serviceProviderEntityId = http(s)://myNexusDomain/callback?client_name=SAML2Client
# Same as the attribute entityID without URI parameter
clients.callbackUrl = http(s)://myNexusDomain/callback

    NOTE: ADFS does not support URI parameter in entityID, remove "?client_name=SAML2Client" from Client ID in the ADFS settings, from serviceProviderEntityId in shiro.ini and from entityID in sp-metadata.xml.

  • metadata.xml - this is the configuration of the identity provider (hereinafter IdP), it needs to be downloaded from Okta/Keycloak/ADFS/Etc and passed into the Nexus container. Additionally, you must specify the "SP Entity ID/Client ID" and "Single sign-on URL/Client SAML endpoint" attributes in the IdP settings, whose value must match the "entityID" from sp-metadata.xml.

  • By default, "Nexus SSO" is already pre-configured for authorization through Okta with HTTP protocol on localhost (the endpoint http://localhost/callback?client_name=SAML2Client, see Okta settings). To configure authorization through another IdP-server is required:

    1. Configure new SAML client in the IdP server with DNS name for your Nexus instance and download metadata.xml.
    2. Replace the protocol and DNS name in sp-metadata.xml and shiro.ini (as show above).
    3. Pass metadata.xml, sp-metadata.xml and shiro.ini to the Nexus container, see _compose.override_prod.yml for an example.

Attributes mapping

The names of user attributes depend on the structure of the profile in IdP. User attribute mapping can be configured in shiro.ini:

# User roles attribute (list of roles)
authorizationGenerator.roleAttributes = roles
# User principal name attribute (user identifier)
pac4jRealm.principalNameAttribute = id

# User profile attributes mapping in one line
pac4jAuthenticationListener.map(attrs) = firstName:myIdpFirstName, lastName:myIdpLastName, email:myIdpEmailaddress
# User profile attributes mapping by separately
pac4jAuthenticationListener.attrs[id] = myIdpUPN
pac4jAuthenticationListener.attrs[firstName] = myIdpFirstName
pac4jAuthenticationListener.attrs[lastName] = myIdpLastName
pac4jAuthenticationListener.attrs[email] = myIdpEmailaddress

NOTE: If variable interpolation is used, such as ${PAC4J_PRINCIPAL_NAME_ATTR:-username}, then the value of the variables must be changed in the .env file. To quickly apply changes, can use hot-reload, see Additional settings (tips and tricks).

Group and role mapping

Roles from Nexus and groups from IdP are mapped to each other by name, for example the role "samltestgroup" in Nexus will be equal to the group "samltestgroup" in IdP. There is no specific way to map specific groups to roles at this time. For mapping, you need to create Nexus roles with the same names as the groups in IdP. In administrative UX will need to create a roles with type "Nexus role" instead of external mapping. After logging in, only those groups that correspond to the roles in Nexus with the same names will be applied to the user, other groups will be ignored.

Debug

To enable debugging, add the following lines to the logback.xml file (output will be to ${NEXUS_DATA}/log/nexus.log):

<logger name="com.github.alanger.nexus.bootstrap.Pac4jAuthenticationListener" level="TRACE" />
<logger name="org.pac4j.saml.client" level="TRACE" />
<logger name="org.opensaml.saml.metadata.resolver" level="TRACE" />

It is better to perform each check in a new private browser window (or delete cookies for Nexus and IdP sites, which is quite difficult), otherwise the browser may remember invalid cookies and will not go to the login page, which in turn confuses and complicates diagnostics.