From 2622bea1f2d7e8402e8766c3fd12e602c63da5b2 Mon Sep 17 00:00:00 2001 From: jasjeetsuri <33685132+jasjeetsuri@users.noreply.github.com> Date: Mon, 10 Dec 2018 11:21:40 +0000 Subject: [PATCH] Update SAML RP Docs Spell check Modify example XMLs to remove internal configs Formatting --- Walkthroughs/RP-SAML.md | 214 +++++++++++++++++++++++----------------- 1 file changed, 123 insertions(+), 91 deletions(-) diff --git a/Walkthroughs/RP-SAML.md b/Walkthroughs/RP-SAML.md index da617f0..01027a9 100644 --- a/Walkthroughs/RP-SAML.md +++ b/Walkthroughs/RP-SAML.md @@ -1,4 +1,4 @@ -Scenario +Scenario - AAD B2C integration with a SAML RP ======== This document will walk you through adding a SAML-based Relying party @@ -45,63 +45,62 @@ add the capability for your tenant to issue SAML tokens. > contains more details around each of the XML elements referenced in > this section.* -1. Open the B2C\_1A\_base.xml policy from your working directory. +1. Open the B2C_1A_TrustFrameworkExtensions.xml policy from your working directory. -2. Find the section with the <ClaimsProviders> and look for the - <ClaimsProvider> with <DisplayName>Token - Issuer</DisplayName> +2. Find the section with the <ClaimsProviders>. -3. Inside of that <ClaimProvider> add the following - <TechnicalProfile> right after the one with Id=”JwtIssuer”: +3. Add the following <ClaimsProvider> and + <TechnicalProfile>: ```xml - - Token Issuer - - SAML2 - - https://login.microsoftonline.com/te/contoso.onmicrosoft.com/SAMLRPPolicy - - - -     - - - - - + + + Token Issuer + + SAML2 + + https://login.microsoftonline.com/te/contoso.onmicrosoft.com/SAMLRPPolicy + + + + + + + + + - - Session Management Provider - - + + Session Management Provider + + ``` 4. Configure Metadata - 1. IssuerUri – Update *contoso.onmicrosoft.com* to your tenant, and *SAMLRPPolicy* to your relying party policy + A. IssuerUri – Update *contoso.onmicrosoft.com* to your tenant, and `SAMLRPPolicy` to your relying party policies `DefaultUserJourney`. This is the IssuerUri that will be returned in the SAML Response from Azure AD B2C. Your relying party must be configured to validate against this Issuer URI during SAML Assertion validation. It can be any string value as long as it is what the application expects. -5. Upload Certs - These are the certificates used to sign the SAML - response. +5. Upload Certificates - These are the certificates used to sign the SAML + response that AAD B2C issues. - 1. (If you don’t have a cert already) Create the cert [using + 1. (If you don’t have a certificate already) Create one [using makecert](http://www.virtues.it/2015/08/howto-create-selfsigned-certificates-with-makecert/) - 1. makecert -r -pe -n + A. makecert -r -pe -n "CN=yourappname.yourtenant.onmicrosoft.com" -a sha256 -sky - signature -len 2048 -e 12/21/2018 -sr CurrentUser -ss My + signature -len 2048 -e 101/01/2020 -sr CurrentUser -ss My YourAppNameSamlCert.cer - 2. Go to cert store “Manage User Certificates” > Current + B. Go to cert store “Manage User Certificates” > Current User > Personal > Certificates > yourappname.yourtenant.onmicrosoft.com - 3. Right click > All Tasks > Export + C. Right click > All Tasks > Export - 4. Yes, export the private key + D. Click Yes, export the private key - 5. Defaults (PFX and first checkbox) + E. Select the defaults (PFX and first checkbox) 2. Go to your Azure AD B2C tenant. Click **Settings > Identity Experience Framework > Policy Keys**. @@ -119,10 +118,10 @@ add the capability for your tenant to issue SAML tokens. 6. Save your changes and upload updated policy - 1. This time, make sure you check the *Overwrite the policy if it + A. This time, make sure you check the *Overwrite the policy if it exists* checkbox. - 2. At this point, this will not have any effect, the intent of + B. At this point, this will not have any effect, the intent of uploading is confirming that what you’ve added thus far doesn’t have any issues. @@ -130,85 +129,99 @@ Add the SAML Relaying Party to User Journey(s) ---------------------------------------------- Now that your tenant can issue SAML tokens, we need to create a user -journey that will be the one issuing this SAML tokens. +journey that will be the one issuing a SAML token. -1. Open the B2C\_1A\_base.xml policy from your working directory. +1. Open the B2C_1A_TrustFrameworkBase.xml policy from your working directory. -2. Find the section with the <UserJourneys> and duplicate the - <UserJourney> with Id=”SignIn” +2. Find the section with the <UserJourneys> and copy the <UserJourney> with Id=SignUpOrSignIn into the B2C_1A_TrustFrameworkExtensions.xml file within the <UserJourneys> section. -3. Rename the Id of that new <UserJourney> (i.e SignInSaml) -4. In the last <OrchestrationStep> (Type=”SendClaims”), modify - the CpimIssuerTechnicalProfileReferenceId value from JwtIssuer to +3. Rename the Id of the new <UserJourney> in the B2C_1A_TrustFrameworkExtensions.xml file (i.e from SignUpOrSignIn to SignUpOrSignInSaml). -Saml2AssertionIssuer +4. In the last <OrchestrationStep> (Type=”SendClaims”), modify + the CpimIssuerTechnicalProfileReferenceId value from JwtIssuer to Saml2AssertionIssuer. -5. Save your changes and upload the updated policy +5. Save your changes and upload the updated policies. -6. Copy the SignIn.xml file +6. Create a copy of the SignUpOrSignin.xml file. -7. Rename it match the Id of the new journey you created (i.e. - SignInSaml) +7. Rename it to help identify its purpose based on its User Journey (i.e. SignUpOrSigninSAML.xml) -8. Modify its PolicyId to a new Guid. +8. Modify the PolicyId in SignUpOrSigninSAML.xml (for example: PolicyId="B2C_1A_SignUpOrSigninSAML"). 9. Update the value of the ReferenceId attribute in the <DefaultUserJourney> to match the Id of of the new journey you - created (i.e. SignInSaml) + created (i.e. SignUpOrSignInSAML) -10. Replace its <RelayingParty> element with the following: +10. Replace its <RelyingParty> element with the following: ```xml - + PolicyProfile + - https://reflector.cpim.localhost.net/saml/reflector.metadata.cacheable.duration.xml - Rsa15 - Aes256 - Sha256 - - - - - - - - + https://yourRelyingParty/Metadata + true + false + true + + + + + + + + + + ``` -11. Update the <Item> with Key=”PartnerEntity“ by adding the URL of the SAML RP’s metadata, if such exists: +11. Update the <Item> with Key="PartnerEntity" by adding the URL of the SAML RP’s metadata, if such exists: - 1. e.g `https://app.com/metadata`; + https://app.com/metadata 12. Save your changes and upload this new policy. +13. When adding claims to the Relying Party policy file, you must add the to the ClaimsSchema for the respective claim name. For example, to output the email claim, you would add the following to the section in the SignUpOrSignInSAML.xml policy file. + + + After which, you must add the following to the in the B2C_1A_TrustFrameworkBase.xml file: + + + + + + + + + urn:oasis:names:tc:SAML:2.0:nameid-format:transient + + + + + + + urn:oasis:names:tc:SAML:2.0:nameid-format:transient + + + + +``` + (Optional) Enable Debugging in your User Journey(s) ---------------------------------------------------- @@ -310,20 +345,17 @@ Relying Party ![](media/image7.png) -The relying party information chooses the user journey to enforce for -the current request. It also chooses the list of claims the relying -party application would like to get as part of the issued token. +The relying party information selects the user journey which will be executed for the authentication request. It also defines the list of claims the relying +party application would like to recieve as part of the issued token. -Multiple applications can use a given policy. They will all receive the -same token with claims and the end user will go through the same user -journey. +Multiple applications can use a given policy. When doing so, all applications using the policy will recieve the same set of claims, and the user will expereince the same user journey. Conversely, a single application can use multiple policies. This allows the application to achieve functionality such as basic sign-in, step-up, sign-up, etc. -To specify the relying party information, a *Relying Party* XML element -must be declared must be declared under the top-level XML element of the +To specify the relying party information, a <RelyingParty> XML element +must be declared under the top-level XML element of the policy XML file. This element is optional. This element contains the following XML elements: @@ -334,8 +366,8 @@ This element contains the following XML elements: |*UserJourneyBehaviors*|0:1|Control the scope of various user journey behaviors.| |*TechnicalProfile*|0:1|Define a technical profile supported by the relying party application. The technical profile provides in this context a contract for the relying party application to contact Azure AD B2C.| -These above *DefaultUserJourney* and *TechnicalProfile* elements must be -declared for any given *RelyingParty* XML element. +The <DefaultUserJourney> and <TechnicalProfile> elements must be +declared for any given <RelyingParty> XML element. The *DefaultUserJourney* XML element contains in turn the following attribute: @@ -423,7 +455,7 @@ Each *OutputClaim* XML element contains the following attributes: |Attribute|Required|Description| |---------|--------|-----------| |*ClaimTypeReferenceId*|True|Specify a reference to a *ClaimType* already defined in the *ClaimsSchema* section in the policy XML file.
Type: String| -|*DefaultValue *|False|Specify a default value if not set.
Type: String| +|*DefaultValue*|False|Specify a default value if not set.
Type: String| |*PartnerClaimType*|False|Specify the partner claim type.
Type: String| |*Required*|False|Specify this claim is required.
Type: String| @@ -452,10 +484,10 @@ how to define a relying party: ```xml - + contoso369b2c.onmicrosoft.com - B2C\_1A\_base-v2 + B2C_1A_base-v2 @@ -463,7 +495,7 @@ how to define a relying party: PolicyProfile - https://reflector.cpim.localhost.net/saml/reflector.metadata.cacheable.duration.xml + https://myApps.com/saml/metadata.xml Rsa15 Aes256 Sha256