SAML2 Authentication

SAML2 Authentication for Specify 7

Specify 7 can be configured to authenticate as a Service Provider (SP) with an Identity Provider (IdP) using SAML2.

Note: This functionality is currently in development.

SP Metadata

SAML2 metadata describing the Specify 7 installation must be created. This XML resource can be created using authoring tools or by hand. The entityID for Specify 7 service should be the Specify 7 root URL plus /saml2_auth/acs/.

For example:

<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     validUntil="2020-05-08T16:19:55Z"
                     cacheDuration="PT604800S"
                     entityID="https://demo.specifycloud.org/saml2_auth/acs/">
    <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                     Location="https://demo.specifycloud.org/saml2_auth/acs/"
                                     index="1" />
        
    </md:SPSSODescriptor>
</md:EntityDescriptor>

The SP metadata should be saved somewhere on the Specify 7 server, /home/specify/servers/demo/spmetadata.xml, for example.

Typically the IdP will require the SP to be registered by importing the metadata in some fashion.

Specify 7 Settings

In the specfiy7/specifyweb/settings directory, copy the example SAML2 settings file, saml2_settings_example.py, to saml2_settings.py and adjust the values as appropriate. In particular, the values shown below will require customization.

SAML2_AUTH = {
    'SAML_CLIENT_SETTINGS': {
        #.
        #.
        #.
        
        'entityid': 'https://demo.specifycloud.org/saml2_auth/acs/',
        'metadata': {
            'local': ['/home/specify/servers/demo/spmetadata.xml'],
            'remote': [{'url': 'https://samltest.id/saml/idp'}]
        },
        
        #.
        #.
        #.
    },

    #.
    #.
    #.
    
    'ATTRIBUTES_MAP': {
        'username': 'uid', # Required.
        #.
        #.
        #.
    },
    
    #.
    #.
    #.
}

The entityid value should be the Specify 7 root URL plus /saml2_auth/acs/. That is, the same value as in the SP metadata.

The SP and IdP metadata should be referenced under the metadata entry. The SP metadata will be the path to the file created in the first step and referenced as 'local': ['PATH_TO_SPMETADATA']. The IdP metadata can be download referenced as a local file in the same 'local': list, or if available online, referenced in a 'remote': clause as shown in the example.

Finally, under ATTRIBUTES_MAP, the username value should be updated to the attribute name in the SAML2 authentication response that corresponds to the Specify user name. Specify users will need to be precreated with user names matching the values provided by the IdP in order to login. Users logging in without a matching Specify user will receive an access denied message.