Define a SAML identity provider technical profile in an Azure Active Directory B2C custom policy

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 exchange

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:

https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com/your-policy/samlp/metadata?idptp=your-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:

Digital encryption

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:

1. Upload a valid X509 certificate with the private key (.pfx file) to the Azure AD B2C policy key store.
2. Add a CryptographicKey element with an identifier of SamlAssertionDecryption to the technical profile CryptographicKeys collection. Set the StorageReferenceId to the name of the policy key you created in step 1.
3. Set the technical profile metadata WantsEncryptedAssertions to true.
4. Update the identity provider with the new Azure AD B2C technical profile metadata. You should see the KeyDescriptor with the use property set to encryption containing 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>

Protocol

The Name attribute of the Protocol element needs to be set to SAML2.

Input claims

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>

Output claims

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 DefaultValue attribute.

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 NameQualifier attribute.

SAML assertion:

<saml:Subject>
  <saml:NameID SPNameQualifier="http://your-idp.com/unique-identifier" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">[email protected]</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>

Output claim:

<OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="http://your-idp.com/unique-identifier" />

If both SPNameQualifier or 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.

Metadata

Cryptographic keys

The CryptographicKeys element contains the following attributes:

Next steps

See the following articles for examples of working with SAML identity providers in Azure AD B2C:

• Add ADFS as a SAML identity provider using custom policies
• Sign in by using Salesforce accounts via SAML