This module is an SAML specific implementation of the authentication plugin architecture of API Secure. Although it has been tested on SURFConext only (running in production) and the open source SAML IdP/SP Mujina, in theory it should work for any SAML 2.0 IdP.

Enable this plugin by:

1. Putting apis-surfconext-authn.jar on the web application classpath (by defining it as a maven dependency in your version of the authorization server war or just by putting it in a classpath directory manually).

2. configuring the correct authentication class in apis.application.properties

    authenticatorClass=org.surfnet.oaaas.conext.SAMLAuthenticator
   

3. Adapt the SAML properties in surfconext.authn.properties to your environment and put it on the classpath. An example of this file resides in apis-authorization-server-war/src/test/resources:

    entityId=http://oaaas-dev
    assertionConsumerURI=http://localhost:8080/oauth2/authorize
    idpUrl=http://localhost:8080/mujina-idp/SingleSignOnService
    idpCertificate=MIICHzCCAYgCCQD7KMJ17XQa7TANBgkqhkiG9w0BAQUFADBUMQswCQYDVQQGEwJOTDEQMA4GA1UECAwHVXRyZWNodDEQMA4GA1UEBwwHVXRyZWNodDEQMA4GA1UECgwHU3VyZm5ldDEPMA0GA1UECwwGQ29uZXh0MB4XDTEyMDMwODA4NTQyNFoXDTEzMDMwODA4NTQyNFowVDELMAkGA1UEBhMCTkwxEDAOBgNVBAgMB1V0cmVjaHQxEDAOBgNVBAcMB1V0cmVjaHQxEDAOBgNVBAoMB1N1cmZuZXQxDzANBgNVBAsMBkNvbmV4dDCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA2slVe459WUDL4RXxJf5h5t5oUbPkPlFZ9lQysSoS3fnFTdCgzA6FzQzGRDcfRj0HnWBdA1YH+LxBjNcBIJ/nBc7Ssu4e4rMO3MSAV5Ouo3MaGgHqVq6dCD47f52b98df6QTAA3C+7sHqOdiQ0UDCAK0C+qP5LtTcmB8QrJhKmV8CAwEAATANBgkqhkiG9w0BAQUFAAOBgQCvPhO0aSbqX7g7IkR79IFVdJ/P7uSlYFtJ9cMxec85cYLmWL1aVgF5ZFFJqC25blyPJu2GRcSxoVwB3ae8sPCECWwqRQA4AHKIjiW5NgrAGYR++ssTOQR8mcAucEBfNaNdlJoy8GdZIhHZNkGlyHfY8kWS3OWkGzhWSsuRCLl78A==
    idpEntityId=http://mock-idp
    spPrivateKey=MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBANrJVXuOfVlAy+EV8SX+YebeaFGz5D5RWfZUMrEqEt35xU3QoMwOhc0MxkQ3H0Y9B51gXQNWB/i8QYzXASCf5wXO0rLuHuKzDtzEgFeTrqNzGhoB6launQg+O3+dm/fHX+kEwANwvu7B6jnYkNFAwgCtAvqj+S7U3JgfEKyYSplfAgMBAAECgYBaPvwkyCTKYSD4Co37JxAJJCqRsQtv7SyXoCl8zKcVqwaIz4rUQRVN/Hv3/WjIFzqB3xLe4mjNYBIF31YWt/6ZslaLL5YJIXISrMgDuQzPKL8VqvvsH9XEpi/qSUsVAWa9Vaqqwa8JTPELK8QhHKaXTxGtatEuW1x6kSNXFCoasQJBAPUaYdj9oCDOGTaOaupF0GB6TIgIItpQESY1Dfpn4cvwB0jH8wBJSBVeBqSa6dg4RI5ydD3J82xlF7NrQnvWpYkCQQDkg26KzQckoJ39HX2gYS4olSeQDAyIDzeCMkj7McDhigy0cL6k9nOQrKlq6V3vkBISTRg7JceJ4z3QE00edXWnAkEAoggv2WBJxIYbOurJmVhP2gffoiomyEYYIDcAp6KXLdffKOkuJulLIv0GzTiwEMWZ5MWbPOHN78Gg+naU/AM5aQJBALfbsANpt4eW28ceBUgXKMZqS+ywZRzL8YOF5gaGH4TYSCSeWiXsTUtoQN/OaFAqAQBMm2Rrn0KoXcGe5fvN0h0CQQDgNLxVcByrVgmRmTPTwLhSfIveOqE6jBlQ8o0KyoQl4zCSDDtMEb9NEFxxvI7NNjgdZh1RKrzZ5JCAUQcdrEQJ
    spCertificate=MIICHzCCAYgCCQD7KMJ17XQa7TANBgkqhkiG9w0BAQUFADBUMQswCQYDVQQGEwJOTDEQMA4GA1UECAwHVXRyZWNodDEQMA4GA1UEBwwHVXRyZWNodDEQMA4GA1UECgwHU3VyZm5ldDEPMA0GA1UECwwGQ29uZXh0MB4XDTEyMDMwODA4NTQyNFoXDTEzMDMwODA4NTQyNFowVDELMAkGA1UEBhMCTkwxEDAOBgNVBAgMB1V0cmVjaHQxEDAOBgNVBAcMB1V0cmVjaHQxEDAOBgNVBAoMB1N1cmZuZXQxDzANBgNVBAsMBkNvbmV4dDCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA2slVe459WUDL4RXxJf5h5t5oUbPkPlFZ9lQysSoS3fnFTdCgzA6FzQzGRDcfRj0HnWBdA1YH+LxBjNcBIJ/nBc7Ssu4e4rMO3MSAV5Ouo3MaGgHqVq6dCD47f52b98df6QTAA3C+7sHqOdiQ0UDCAK0C+qP5LtTcmB8QrJhKmV8CAwEAATANBgkqhkiG9w0BAQUFAAOBgQCvPhO0aSbqX7g7IkR79IFVdJ/P7uSlYFtJ9cMxec85cYLmWL1aVgF5ZFFJqC25blyPJu2GRcSxoVwB3ae8sPCECWwqRQA4AHKIjiW5NgrAGYR++ssTOQR8mcAucEBfNaNdlJoy8GdZIhHZNkGlyHfY8kWS3OWkGzhWSsuRCLl78A==
    samlUuidAttribute=urn:mace:dir:attribute-def:uid
    openConextApiClient=org.surfnet.oaaas.conext.mock.OpenConextOAuthClientMock
    api-enrich-principal=false
    admin.client.apis.teamname=urn\:collab\:group\:dev.surfteams.nl\:nl\:surfnet\:diensten\:admin_apis
   

• entityId is defined and provided by SURFnet.
• assertionConsumerURI is a URI that clients (browsers) can resolve and be redirected to by the SAML IdP.
• idpUrl is the public URL of the IdP's endpoint.
• idpCertificate is the public key of the IdP, without newlines and head/foot lines (containing --- BEGIN CERTIFI... etc.) Defined and provided by SURFnet.
• spPrivateKey is the private key of Apis for the given setup. To be generated by the SP.
• spCertificate is the public key of Apis for the given setup. To be generated by the SP.
• samlUuidAttribute is the SAML attribute that contains the unique identifier of the logged in user
• openConextApiClient is the class name of an additional resource server client to enrichen the Principal
• api-enrich-principal enables / disables the enrichement of the principal.
• admin.client.apis.teamname defines a team whose members will be granted admin privilege. This means: can manage all resource servers and clients.

The spPrivateKey and the spCertificate can be generated by the following commands:

    openssl req -subj '/O=Organization, CN=APIS (TEST)/' -newkey rsa:2048 -new -x509 -days 3652 -nodes -out idp.crt -keyout idp.pem

Strip whitespace and the heading and footer from the files and use the result as the value.

In practice, use this command to obtain the value for the key:

    cat idp.pem |head -n -1 |tail -n +2 | tr -d '\n'; echo

In practice, use this command to obtain the value for the certificate:

    cat idp.crt |head -n -1 |tail -n +2 | tr -d '\n'; echo

To modify behaviour of this plugin, extend (one of) the following classes and wire them accordingly.

This class is the main entry point and the easiest to extend. Refer to your subclass in apis.application.properties with the property authenticatorClass

This class is instantiated by SAMLAuthenticator.createProvisioner(). So extend SAMLAuthenticator (see above) and override this method.

This class is instantiated by SAMLAuthenticator.createOpenSAMLContext(Properties, SAMLProvisioner). So extend SAMLAuthenticator (see above) and override this method.