Introduction

A SAML Authentication Request is initiated by the service provider / client to request the identity provider to authenticate a user. This request is typically generated when a user attempts to access a service that requires authentication and their current session is not authenticated. The request informs the identity provider that a user needs verification and prompts the IdP to either initiate a login process or verify the existing authentication state.

The primary purpose of the SAML Authentication Request is to facilitate secure and efficient communication between the service provider and the identity provider and looks something like that:

<samlp:AuthnRequest
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="_192b8d3f6562e8a2f8a1a3e49e5d6ec2"
    Version="2.0"
    IssueInstant="2024-05-03T08:21:00Z"
    Destination="https://idp.example.com/SAML2/SSO/Service"
    AssertionConsumerServiceURL="https://sp.example.com/SAML2/SSO/Response"
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">
    
    <saml:Issuer>https://sp.example.com/SAML2</saml:Issuer>
    
    <samlp:NameIDPolicy
        Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
        AllowCreate="true"/>
    
    <samlp:RequestedAuthnContext Comparison="exact">
        <saml:AuthnContextClassRef>
            urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
        </saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

SAML Scoping

Scoping in the context of SAML is a mechanism used to refine or restrict the processing of authentication and attribute queries. This feature is particularly useful in federated identity environments, where a user's identity and authentication information might be managed across various external identity providers (IdPs). Scoping allows a service provider / client to specify which IdPs should be involved in the authentication process or from where the attributes should be sourced.

Key Elements of SAML Scoping

SAML scoping involves several key elements that can be included in an AuthnRequest:

ProxyCount: This optional attribute specifies the maximum number of proxying hops that are permitted to occur when processing this request. This feature is currently not yet implemented.
IDPList: A list of IdPs that are allowed or suggested to be used for handling the request. This is particularly useful in scenarios where the user or the service provider wants to limit which IdPs can respond.

Scoping with IDPList

The IDPList element within a SAML AuthnRequest specifies the IdPs that are preferred or required for processing the authentication request. It consists of one or more IDPEntry elements, each representing an IdP. Each IDPEntry includes:

ProviderID: The unique identifier of the IdP, which has to match the authentication scheme of the external identity provider in the CoreOne Suite Configuration.
Name: A human-readable name for the IdP, useful in user interfaces.
Loc: An optional attribute that provides a location (URL) where the IdP can be reached.

Example: SAML Authentication Request with Scoping

Consider a scenario where a service provider wants to ensure that authentication requests are handled only by specific IdPs. Here is an example of how a SAML AuthN Request with scoping might be structured:

<samlp:AuthnRequest
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="_b23455dc9a8b7c8d9e8f7g6h5i4j3k2l1"
    Version="2.0"
    IssueInstant="2024-05-03T12:00:00Z"
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
    AssertionConsumerServiceURL="https://sp.example.com/SAML2/SSO/Response"
    Destination="https://idp.example.com/SAML2/SSO/Service">
    
    <saml:Issuer>https://sp.example.com/SAML2</saml:Issuer>

    <samlp:Scoping>
        <samlp:IDPList>
            <samlp:IDPEntry ProviderID="https://idp1.example.com"
                            Name="IDP One"
                            Loc="https://idp1.example.com/Service"/>
            <samlp:IDPEntry ProviderID="https://idp2.example.com"
                            Name="IDP Two"
                            Loc="https://idp2.example.com/Service"/>
        </samlp:IDPList>
    </samlp:Scoping>
</samlp:AuthnRequest>

Note: If the client configuration allows for other local authentication methods or other IdPs, only the ones that match the IDPList will be displayed. All other will be discarded.

Local Provider: cos_local

If you also want to allow any of the configured and available local authentication methods, you can pass along the following IDPEntry in the AuthnRequst:

<samlp:IDPEntry ProviderID="cos_local" />