Define a SAML identity provider technical profile in an Azure Active Directory B2C custom policy
In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. For most scenarios, we recommend that you use built-in user flows. If you've not done so, learn about custom policy starter pack in Get started with custom policies in Active Directory B2C.
Azure Active Directory B2C (Azure AD B2C) provides support for the SAML 2.0 identity provider. This article describes the specifics of a technical profile for interacting with a claims provider that supports this standardized protocol. With a SAML technical profile you can federate with a SAML-based identity provider, such as ADFS and Salesforce. This federation allows your users to sign in with their existing social or enterprise identities.
Metadata is information used in the SAML protocol to expose the configuration of a SAML party, such as a service provider or identity provider. Metadata defines the location of the services, such as sign-in and sign-out, certificates, sign-in method, and more. The identity provider uses the metadata to know how to communicate with Azure AD B2C. The metadata is configured in XML format and may be signed with a digital signature so that the other party can validate the integrity of the metadata. When Azure AD B2C federates with a SAML identity provider, it acts as a service provider initiating a SAML request and waiting for a SAML response. And, in some cases, accepts unsolicited SAML authentication, which is also known as identity provider initiated.
The metadata can be configured in both parties as "Static Metadata" or "Dynamic Metadata". In static mode, you copy the entire metadata from one party and set it in the other party. In dynamic mode, you set the URL to the metadata while the other party reads the configuration dynamically. The principles are the same, you set the metadata of the Azure AD B2C technical profile in your identity provider and set the metadata of the identity provider in Azure AD B2C.
Each SAML identity provider has different steps to expose and set the service provider, in this case Azure AD B2C, and set the Azure AD B2C metadata in the identity provider. Look at your identity provider’s documentation for guidance on how to do so.
The following example shows a URL address to the SAML metadata of an Azure AD B2C technical profile:
Replace the following values:
- your-tenant-name with your tenant name, such as fabrikam.b2clogin.com.
- your-policy with your policy name. Use the policy where you configure the SAML provider technical profile, or a policy that inherits from that policy.
- your-technical-profile with your SAML identity provider technical profile name.
Digital signing certificates exchange
To build a trust between Azure AD B2C and your SAML identity provider, you need to provide a valid X509 certificate with the private key. You upload the certificate with the private key (.pfx file) to the Azure AD B2C policy key store. Azure AD B2C digitally signs the SAML sign-in request using the certificate that you provide.
The certificate is used in the following ways:
- Azure AD B2C generates and signs a SAML request, using the Azure AD B2C private key of the certificate. The SAML request is sent to the identity provider, which validates the request using Azure AD B2C public key of the certificate. The Azure AD B2C public certificate is accessible through technical profile metadata. Alternatively, you can manually upload the .cer file to your SAML identity provider.
- The identity provider signs the data sent to Azure AD B2C using the identity provider's private key of the certificate. Azure AD B2C validates the data using the identity provider's public certificate. Each identity provider has different steps for setup, look at your identity provider’s documentation for guidance on how to do so. In Azure AD B2C, your policy needs access to the certificate public key using the identity provider's metadata.
A self-signed certificate is acceptable for most scenarios. For production environments, it is recommended to use an X509 certificate that is issued by a certificate authority. Also, as described later in this document, for a non-production environment you can disable the SAML signing on both sides.
The following diagram shows the metadata and certificate exchange:
To encrypt the SAML response assertion, the identity provider always uses a public key of an encryption certificate in an Azure AD B2C technical profile. When Azure AD B2C needs to decrypt the data, it uses the private portion of the encryption certificate.
To encrypt the SAML response assertion:
- Upload a valid X509 certificate with the private key (.pfx file) to the Azure AD B2C policy key store.
- Add a CryptographicKey element with an identifier of
SamlAssertionDecryptionto the technical profile CryptographicKeys collection. Set the StorageReferenceId to the name of the policy key you created in step 1.
- Set the technical profile metadata WantsEncryptedAssertions to
- Update the identity provider with the new Azure AD B2C technical profile metadata. You should see the KeyDescriptor with the use property set to
encryptioncontaining the public key of your certificate.
The following example shows the Key Descriptor section of the SAML metadata used for encryption:
<KeyDescriptor use="encryption"> <KeyInfo xmlns="https://www.w3.org/2000/09/xmldsig#"> <X509Data> <X509Certificate>valid certificate</X509Certificate> </X509Data> </KeyInfo> </KeyDescriptor>
The Name attribute of the Protocol element needs to be set to
The InputClaims element is used to send a NameId within the Subject of the SAML AuthN Request. To achieve this add an input claim with a PartnerClaimType set to
subject as shown below.
<InputClaims> <InputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="subject" /> </InputClaims>
The OutputClaims element contains a list of claims returned by the SAML identity provider under the
AttributeStatement section. You may need to map the name of the claim defined in your policy to the name defined in the identity provider. You can also include claims that aren't returned by the identity provider as long as you set the
Subject name output claim
To read the SAML assertion NameId in the Subject as a normalized claim, set the claim PartnerClaimType to value of the
SPNameQualifier attribute. If the
SPNameQualifierattribute is not presented, set the claim PartnerClaimType to value of the
<saml:Subject> <saml:NameID SPNameQualifier="http://your-idp.com/unique-identifier" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">firstname.lastname@example.org</saml:NameID> <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <SubjectConfirmationData InResponseTo="_cd37c3f2-6875-4308-a9db-ce2cf187f4d1" NotOnOrAfter="2020-02-15T16:23:23.137Z" Recipient="https://your-tenant.b2clogin.com/your-tenant.onmicrosoft.com/B2C_1A_TrustFrameworkBase/samlp/sso/assertionconsumer" /> </SubjectConfirmation> </saml:SubjectConfirmation> </saml:Subject>
<OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="http://your-idp.com/unique-identifier" />
NameQualifier attributes are not presented in the SAML assertion, set the claim PartnerClaimType to
assertionSubjectName. Make sure the NameId is the first value in assertion XML. When you define more than one assertion, Azure AD B2C picks the subject value from the last assertion.
The following example shows the claims returned by a SAML identity provider:
- The issuerUserId claim is mapped to the assertionSubjectName claim.
- The first_name claim is mapped to the givenName claim.
- The last_name claim is mapped to the surname claim.
- The displayName claim is mapped to the name claim.
- The email claim without name mapping.
The technical profile also returns claims that aren't returned by the identity provider:
- The identityProvider claim that contains the name of the identity provider.
- The authenticationSource claim with a default value of socialIdpAuthentication.
<OutputClaims> <OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="assertionSubjectName" /> <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="first_name" /> <OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="last_name" /> <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" /> <OutputClaim ClaimTypeReferenceId="email" /> <OutputClaim ClaimTypeReferenceId="identityProvider" DefaultValue="contoso.com" /> <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="socialIdpAuthentication" /> </OutputClaims>
The OutputClaimsTransformations element may contain a collection of OutputClaimsTransformation elements that are used to modify the output claims or generate new ones.
|PartnerEntity||Yes||URL of the metadata of the SAML identity provider. Or copy the identity provider metadata and embed it inside the CDATA element
|WantsSignedRequests||No||Indicates whether the technical profile requires all of the outgoing authentication requests to be signed. Possible values:
|XmlSignatureAlgorithm||No||The method that Azure AD B2C uses to sign the SAML request. This metadata controls the value of the SigAlg parameter (query string or post parameter) in the SAML request. Possible values:
|WantsSignedAssertions||No||Indicates whether the technical profile requires all incoming assertions to be signed. Possible values:
|WantsEncryptedAssertions||No||Indicates whether the technical profile requires all incoming assertions to be encrypted. Possible values:
|NameIdPolicyFormat||No||Specifies constraints on the name identifier to be used to represent the requested subject. If omitted, any type of identifier supported by the identity provider for the requested subject can be used. For example,
|NameIdPolicyAllowCreate||No||When using NameIdPolicyFormat, you can also specify the
|AuthenticationRequestExtensions||No||Optional protocol message extension elements that are agreed on between Azure AD BC and the identity provider. The extension is presented in XML format. You add the XML data inside the CDATA element
|IncludeAuthnContextClassReferences||No||Specifies one or more URI references identifying authentication context classes. For example, to allow a user to sign in with username and password only, set the value to
|IncludeKeyInfo||No||Indicates whether the SAML authentication request contains the public key of the certificate when the binding is set to
|IncludeClaimResolvingInClaimsHandling||No||For input and output claims, specifies whether claims resolution is included in the technical profile. Possible values:
|SingleLogoutEnabled||No||Indicates whether during sign-in the technical profile attempts to sign out from federated identity providers. For more information, see Azure AD B2C session sign-out. Possible values:
|ForceAuthN||No||Passes the ForceAuthN value in the SAML authentication request to determine if the external SAML IDP will be forced to prompt the user for authentication. By default, Azure AD B2C sets the ForceAuthN value to false on initial login. If the session is then reset (for example by using the
The CryptographicKeys element contains the following attributes:
|SamlMessageSigning||Yes||The X509 certificate (RSA key set) to use to sign SAML messages. Azure AD B2C uses this key to sign the requests and send them to the identity provider.|
|SamlAssertionDecryption||No||The X509 certificate (RSA key set). A SAML identity provider uses the public portion of the certificate to encrypt the assertion of the SAML response. Azure AD B2C uses the private portion of the certificate to decrypt the assertion.|
|MetadataSigning||No||The X509 certificate (RSA key set) to use to sign SAML metadata. Azure AD B2C uses this key to sign the metadata.|
SAML entityID customization
If you have multiple SAML applications that depend on different entityID values, you can override the
issueruri value in your relying party file. To do this, copy the technical profile with the "Saml2AssertionIssuer" ID from the base file and override the
<ClaimsProviders> section from the base and preserve these elements within the claims provider:
<TechnicalProfile Id="Saml2AssertionIssuer">, and
<ClaimsProviders> <ClaimsProvider> <DisplayName>Token Issuer</DisplayName> <TechnicalProfiles> <TechnicalProfile Id="Saml2AssertionIssuer"> <DisplayName>Token Issuer</DisplayName> <Metadata> <Item Key="IssuerUri">customURI</Item> </Metadata> </TechnicalProfile> </TechnicalProfiles> </ClaimsProvider> </ClaimsProviders> <RelyingParty> <DefaultUserJourney ReferenceId="SignUpInSAML" /> <TechnicalProfile Id="PolicyProfile"> <DisplayName>PolicyProfile</DisplayName> <Protocol Name="SAML2" /> <Metadata> …
See the following articles for examples of working with SAML identity providers in Azure AD B2C: