Skip to main content

Reference

In this section, you'll find a detailed explanation of the available options for setting up an external Service Provider (SP) and configuring the attributes that the Monokee Identity Provider (IDP) will need to send to it to enable Single Sign-On (SSO).

Service Provider Configuration​

Service provider metadata​

The SP could be configured importing data from a metadata. A metadata could be imported in two ways:

  • Load from file: A browser window will be open allowing to choose metadata from xml files present in your drive.

  • Load by URL: You can paste string an URL that point to the metadata you want to load.

Monokee automatically completes the fields reading data from SP metadata. Once the metadata import is completed, you can manually add, remove, or modify the configurations as needed.

General information​

  • Entity identifier: This is the entity ID of the SP. An entity in SAML refers to any party that participates in the SAML protocol. Entity ID is the identifier of the entity.

  • Metadata ID: This identifier is a unique identifier for the SP's metadata document.

Signing options​

  • SP signs authentication requests: This option, present in the SP metadata, tells the IDP if the incoming authentication requests are signed. If the authentication request is not signed the IDP rejects it.

  • SP requires signed assertions: This option, present in the SP metadata, tells the IDP if the assertion must be signed.

Signature​

This is a list of certificates that are valid for the SP. The IDP will use this list to validate any signed messages received from the SP. If the SP includes a certificate in the XML message it sends to the IDP, that certificate must be present in this list in order to be successfully validated by the IDP. For each certificate, the subject is listed.

Assertion consumer services​

The Assertion Consumer Service (ACS) is the endpoint where the IDP sends to SP the SAML response containing the assertion that confirms the user's identity. Different protocols could be use to transport SAML assertion, these methods are called bindings. A SP has the flexibility to define one or multiple ACS endpoints, each of which can be associated with a specific binding protocol. The SP may use an index to uniquely identify an endpoint when multiple endpoints with the same binding are present. Each endpoint is fully defined by three values:

info

Monokee allows the import of unsupported bindings from SP metadata, but it will not utilize them in any way. This import feature is provided to facilitate their potential use in the future.

  • Binding: Is the protocol supported by the endpoint. The supported values from Monokee are:

    • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST: This binding is used for sending SAML Response containing assertion. To send these messages, they are first encoded in Base64 format and included as the value of a parameter in the body of an HTTP POST request. The content type of this request is usually set to application/x-www-form-urlencoded, which allows for the message to be transmitted as key-value pairs in the request body.

  • Index: Is the number that uniquely identifies the endpoint within a set of endpoints of the same type.

- **Is default**: This property indicates whether the endpoint is the preferred one. It's used in the IDP-initiated flow to determine the correct endpoint for sending the SAML response that contains the user's information.
  • Location: Is the the URL of the endpoint where the SP expects to receive the SAML assertion from the IDP.

Single logout services​

The Single Logout Service (SLS) is the endpoint where the IDP sends to SP the Logout requests and responses. As per ACS, different bindings could be use to transport Logout request and response. A SP has the flexibility to define one or multiple SLS endpoints, each of which can be associated with a specific binding protocol. Each endpoint is fully defined by three values:

info

Monokee allows the import of unsupported bindings from SP metadata, but it will not utilize them in any way. This import feature is provided to facilitate their potential use in the future.

  • Binding: Is the protocol supported by the endpoint. The supported values from Monokee are:

    • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST: This binding is used for sending SAML Logout Request or Response messages. To send these messages, they are first encoded in Base64 format and included as the value of a parameter in the body of an HTTP POST request. The content type of this request is usually set to application/x-www-form-urlencoded, which allows for the message to be transmitted as key-value pairs in the request body.
    • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect: This binding is used for sending SAML Logout Request or Response messages. To send these messages, they are first deflated and encoded in Base64 format, and then included as part of the URL parameters in the Location header of a 302 HTTP response, allowing for the messages to be transmitted via HTTP Redirect.

  • Location: Is the the URL of the endpoint where the SP expects to receive the Logout Request from the IDP.

  • Response location: Is the the URL of the endpoint where the SP expects to receive the Logout Response from the IDP.

Additional Configuration​

Additional Configuration​

  • Identity provider: The Monokee IDP name that you want to use to interact with the SP.

  • Signature algorithm: SAML 2.0 supports several signature algorithms for signing and verifying SAML assertions and messages. The choice of SAML signature algorithm should be based on the specific security requirements of the use case and the cryptographic capabilities of the parties involved. The algorithm chosen in this context, is the signing algorithm that the IDP will use to sign the SAML response. This algorithm is also used from IDP to sign logout requests and responses.

    The following signature algorithms are supported:

    • RSA with SHA-1: This algorithm uses RSA for digital signatures and SHA-1 for message digest. It is considered weak and is no longer recommended.
    • RSA with SHA-256: This algorithm uses RSA for digital signatures and SHA-256 for message digest. It is considered secure and is widely used. It's the default value for Monokee
    • RSA with SHA-384: This algorithm uses RSA for digital signatures and SHA-384 for message digest. It provides higher security than RSA with SHA-256 and is suitable for high-security applications.
    • RSA with SHA-512: This algorithm uses RSA for digital signatures and SHA-512 for message digest. It provides the highest level of security among the supported algorithms but is not widely used due to its computational cost.

  • Digest algorithm: To understand this parameter, a brief introduction is necessary. When creating a digital signature, the message is first hashed using a cryptographic hash function. The resulting digest (the output of the hash function) is then encrypted using the private key of the signing party. The receiving party can then verify the signature by computing the digest on the received message using the same hash function and decrypting the signature using the public key of the signing party. If the two digests match, the signature is valid.

    If this parameter is not configured, the digest algorithm used is derived from the signing algorithm and the corresponding hash function is used. This configuration is not reported in the SP's metadata and so the information will be used only by the IDP as a digest method when it signs the SAML responses, assertions, logout requests and responses. A method supported by the SP must be chosen. The possible values are:

    • SHA-1: This is the default digest algorithm for SAML 1.1 and is still supported in SAML 2.0, although its use is discouraged due to known vulnerabilities.
    • SHA-256: This is the recommended digest algorithm for SAML 2.0 and provides stronger security than SHA-1. It's the default value for Monokee
    • SHA-384: This algorithm provide even stronger security than SHA-256, but it's not widely used in SAML.
    • SHA-512: This algorithm provide the highest level of security but it's not very used due to its computational cost.

Identity provider signing options​

  • IDP signs post responses: This option tells the IDP if the SAML responses must be signed.
  • IDP signs logout requests: This option tells the IDP if the logout requests must be signed.
  • IDP signs logout responses: This option tells the IDP if the logout responses must be signed.
  • IDP requires signed logout requests: This option tells if the IDP requires signed logout requests. If the SP sends a not signed logout request the IDP rejects it.
  • IDP requires signed logout responses: This option tells if the IDP requires signed logout responses. If the SP sends a not signed logout response the IDP rejects it.

Response Statement Configuration​

Authentication Statement​

An Authentication Statement is a component of a SAML assertion that indicates that the user has been authenticated by an IDP. It contains information such as the method of authentication used, the time of authentication, and potentially other relevant details about the authentication process. This statement provides assurance to the SP that the user has been authenticated by a trusted party.

  • Subject format: Is an attribute that specifies the format of the identifier used to represent a user or entity in a SAML assertion. Possible values are:
    • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent: This format indicates that the NameID is a persistent identifier that is guaranteed to be unique within the scope of the IDP and SP involved in the SAML exchange. This is often used in cases where the SP needs to maintain a long-term relationship with the user or entity, even if the user's identifier changes over time.
    • urn:oasis:names:tc:SAML:2.0:nameid-format:transient: This format indicates that the NameID is a transient identifier that is not guaranteed to be unique over time, but is unique within the scope of the current SAML exchange. This is often used in cases where the SP does not need to maintain a long-term relationship with the user or entity. If this format is chosen, the Subject Mapping Rule is not available and a random uuid will be used as user identifier.
    • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress: This format indicates that the NameID is an email address that uniquely identifies the user or entity. This is often used in cases where the user's email address is their primary identifier.
    • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified: This format indicates that the NameID format is not specified.
    • urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName: This format indicates that the NameID is an X.509 subject name that uniquely identifies the user or entity. This is often used in cases where digital certificates are used for authentication.
    • urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName: This format indicates that the NameID is a Windows domain-qualified name that uniquely identifies the user or entity.
    • urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos: This format indicates that the NameID is a Kerberos principal name that uniquely identifies the user or entity. This is often used in cases where Kerberos is used for authentication.
    • urn:oasis:names:tc:SAML:2.0:nameid-format:entity: This format indicates that the NameID represents a SAML entity, such as an IDP or an SP. This is often used in cases where the NameID is used to identify the entity involved in a SAML exchange.
- **Subject Name Qualifier**: The subject name qualifier is an optional attribute that can be included in a SAML assertion to qualify the NameID attribute of the subject being authenticated. The subject name qualifier is used to provide additional context or specificity about the identity of the subject.
  • Subject confirmation method: This is the Subject Confirmation Method (SCM) you want to use to verify the identity of a user in the SAML assertion. Possible values are:
    • urn:oasis:names:tc:SAML:2.0:cm:bearer: With this method, the SAML assertion is issued to the subject without any additional verification, the relying party must trust the identity provider to authenticate the subject. This is also the default and most common value.
    • urn:oasis:names:tc:SAML:2.0:cm:sender-vouches: With this method, the SAML assertion is issued to the subject without any additional verification, such as a digital signature or a message authentication code (MAC). The relying party must trust the identity provider to authenticate the subject.
    • urn:oasis:names:tc:SAML:2.0:cm:holder-of-key: With this method, the assertion includes a digital signature or MAC that is used to verify the identity of both the subject and the holder of a specific key, such as a private key. The relying party must trust both the identity provider and the holder of the key to authenticate the subject.
info

Monokee supports urn:oasis:names:tc:SAML:2.0:cm:bearer only, other values are documented to facilitate their potential use in the future.

  • Subject mapping rule: With this configuration you can map user's attribute to the assertion subject.

Attribute Statement​

An Attribute Statement is a component of a SAML assertion that contains information about the user, such as their name, email address, or other attributes. This information is provided by the IDP and is typically based on the user's profile attributes.

  • Attribute mapping rule: With this configuration you can map user's attributes to attributes that will be sent in the assertion to SP. Attribute keys can be chosen from the list of attributes supported by the IDP, or they can be anything if the IDP does not specify any particular attribute. Attribute values can be a combination of domain custom attributes manipulated by different functions: slice, substring, toUpperCase, toLowerCase, split, trim, prepend, concat, replace.

    An example of an attribute mapping entry could be:

    new_email: email.split("@")[0] + domain_id.concat(".example.org").prepend("@")

    This transformation rule assign to attribute new_email the value calculated with the following steps:

    • The email.split("@")[0] expression extracts the user's email username before the "@" symbol.
    • The domain_id attribute contains the user's domain id.
    • The concat(".example.org") function concatenates the domain id with the ".example.org" domain name.
    • The resulting string is then prepended with the "@" symbol using the prepend("@") function to create a valid email address.