Table of Contents

Mapping SAML authnContextClassRef to OIDC amr Claim in PhenixID Authentication Services as a SAML Proxy

This article provides instructions for mapping the SAML authnContextClassRef attribute to the OIDC amr (Authentication Methods References) claim when PhenixID Authentication Services (PAS) is configured as a SAML federation broker or proxy. Acting as a SAML proxy, PAS enables seamless identity federation between SAML Identity Providers (IdPs) and Service Providers (SPs) while allowing OIDC-based applications to interpret the authentication strength used by the original SAML IdP.

Purpose of Mapping authnContextClassRef to amr in a SAML Proxy Flow

  • authnContextClassRef: In SAML, the authnContextClassRef attribute indicates the authentication method and strength used by the SAML IdP, such as password-based, multi-factor, or certificate-based authentication.
  • amr Claim: In OIDC, the amr claim serves a similar purpose by identifying the authentication method(s) used. Mapping authnContextClassRef to amr ensures that the authentication context is preserved across protocols, allowing OIDC applications to enforce consistent security policies based on the authentication strength used by the SAML IdP.

SAML to OIDC Mapping Table

The table below provides example mappings from authnContextClassRef values to the corresponding OIDC amr claim values. These mappings help ensure that the authentication context from the SAML IdP is accurately represented in the OIDC flow, enabling applications to recognize and apply appropriate access controls.

SAML authnContextClassRef Value OIDC amr Value
urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport ["pwd"]
urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract ["otp", "mfa"]
urn:oasis:names:tc:SAML:2.0:ac:classes:XMLDSig ["swk", "mfa"]
urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient ["swk", "mfa"]
urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos ["wia"]
urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI ["sc", "mfa"]

Configuration Steps for Mapping in PhenixID as a SAML Proxy

To configure this mapping in PAS when acting as a SAML proxy, follow these steps:

  1. Open the Configuration Manager:

    • Access the PAS Configuration Manager and select the SPBroker scenario to modify the execution flow.

  2. Map authnContextClassRef Values:

    • Add a PropertyValueMapping valve to map the authncontextclassref values to amr based on the table provided above. Each entry in the mapping corresponds to an authentication strength that the OIDC Relying Party (RP) can interpret.

    • Example mappings:

      urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport|pwd,
urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract|otp,
urn:oasis:names:tc:SAML:2.0:ac:classes:XMLDSig|swk,
urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient|swk,
urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos|wia,
urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI|sc

    • Example valve:

      {
    "name": "PropertyValueMapping",
    "config": {
        "source": "{{item.authncontextclassref}}",
        "dest": "amr",
        "mapping_table": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport|pwd,urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract|otp,urn:oasis:names:tc:SAML:2.0:ac:classes:XMLDSig|swk,urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient|swk,urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos|wia,urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI|sc"
    }
}

      Note: In JSON strings, line breaks should be represented using \n or the entire string should be kept on a single line.

  3. Add Multi-Factor Authentication (mfa) Logic:

    • Include a PropertyAddValve with name = amr and value = mfa. Configure it to skip adding mfa if amr contains "pwd" or "wia", ensuring mfa is only added when appropriate.

    • Example valve:

      {
    "name": "PropertyAddValve",
    "config": {
        "name": "amr",
        "value": "mfa",
        "splitter": ",",
        "skip_if_expr": "flow.getPropertyValue('amr', '').contains('pwd') || flow.getPropertyValue('amr', '').contains('wia')"
    }
}

Finalizing amr in the id_token Using the OpenID Scope Configuration

To include the amr claim within the OpenID scope, configure it as follows in PAS:

  1. Access the OpenID Scope in PAS:

    • In PAS, navigate to Scenarios -> OIDC and locate the OpenID scope configuration.

  2. Define amr as an Array in the Claim Configuration:

    • In the claim configuration for amr, specify that it should be treated as an array to support multiple authentication methods if applicable:

      {
  "name": "amr",
  "type": "array"
}

Example Pipe Configuration for Mapping authnContextClassRef to amr in PAS

Below is an example of a complete execution flow configuration in PAS, including the final step to map and add the amr claim based on the transformed authncontextclassref values.

{
    "id": "authncontextclassref-to-amr-mapping-pipe",
    "valves": [
        {
            "name": "ItemCreateValve",
            "enabled": "true",
            "config": {
                "dest_id": "user"
            }
        },
        {
            "name": "AssertionConsumer",
            "config": {
                "clock_skew_minutes": "10",
                "addAttributesTo": "item"
            }
        },
        {
            "name": "FlowFailValve",
            "config": {
                "message": "User does not exist",
                "exec_if_expr": "flow.items().isEmpty()"
            }
        },
        {
            "name": "PropertyValueMapping",
            "config": {
                "source": "{{item.authncontextclassref}}",
                "dest": "amr",
                "mapping_table": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport|pwd,urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract|otp,urn:oasis:names:tc:SAML:2.0:ac:classes:XMLDSig|swk,urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient|swk,urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos|wia,urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI|sc"
            }
        },
        {
            "name": "PropertyAddValve",
            "config": {
                "name": "amr",
                "value": "mfa",
                "splitter": ",",
                "skip_if_expr": "flow.getPropertyValue('amr', '').contains('pwd') || flow.getPropertyValue('amr', '').contains('wia')"
            }
        }
    ]
}

Explanation of Pipe Configuration

  • ItemCreateValve: Creates a new item in the flow with the ID "user", preparing a container for user attributes and subsequent processing.
  • AssertionConsumer: Consumes the SAML assertion and adds the extracted attributes to the item in the flow. It allows for a clock skew of up to 10 minutes to accommodate time discrepancies between systems.
  • FlowFailValve: Halts the flow with the message "User does not exist" if no items are present after assertion consumption, ensuring that processing does not continue without a valid user.
  • PropertyValueMapping: Maps the authncontextclassref values from the item to corresponding amr (Authentication Methods References) values based on the provided mapping table. This enables compatibility with OIDC-compliant claim values.
  • PropertyAddValve: Adds "mfa" to the amr property unless the amr contains "pwd" or "wia", ensuring that multi-factor authentication context is correctly represented when applicable.

This setup ensures that PAS, when acting as a SAML proxy, effectively translates SAML authentication strength indicators into OIDC amr claims within the OpenID scope. By preserving the authentication context in this way, OIDC Relying Parties can enforce consistent access policies based on the original SAML authentication method, supporting secure and streamlined access across federated systems.

OIDC (OpenID Connect) SAML 2