Creating an identity mapping data instance

If you use OAuth 2.0 Client Registration instances that authenticate users through a SAML 2.0 Assertion, JSON Web Token, or custom source, you need to specify how the Pega server identifies an operator and how to map the user identity information for use in the Pega application.

You also need an identity mapping if you create a token credentials authentication service. Use the Identity Mapping data instance to create a token profile, and map attributes, claims, or password credentials to operator record properties to identify an operator.
  1. In in the navigation panel of Dev Studio, click Records > Security > Identity Mapping.
  2. Click Create.
  3. In the Name field, enter the name of the identity mapping profile.
  4. In the Short description field, enter a short description of the identity mapping profile.
  5. In the Source field, choose one of the following options to select the source of the Identity Mapping.
    • SAML 2.0 Assertion – Select to map operator attributes from a SAML 2.0 Assertion source.
      1. Click Create and open.
      2. In the Signature verification section, in the Truststore field, press the Down arrow key and select the same keystore that is used by the SAML 2.0 Assertion and that verifies the token.
      3. In the Operator identification section, select mapping the operator ID from either Name identifier in the subject or Attribute.
        • If you select Attribute, enter an expression to indicate the attribute name.
      4. In the Attribute Mappings section, map one or more attributes to property names. For example, enter an attribute to map the .pyUserIdentifier property to identify an existing operator.
      5. In the Processing options section, in the Post processing activity field, enter the name of your postprocessing activity. The postprocessing activity can connect to any external entity to get additional data, and enrich the OperatorID page with attributes that are available on the assertion page. To facilitate writing the postprocessing activity, you can use the pzSAMLBearerIdentityMappingAct activity as a reference.
    • JSON Web Token – Select to map operator attributes from a JSON Web Token source.
      CAUTION:
      You need to create a new identity mapping instance and token profile. In the token profile, specify the Issuer and Audience claim in the Claim validation section, the Subject and Expiration Time claim in the Claims mapping section, and a keystore in the Truststore field. For more information, see Processing a JSON Web Token.
      1. Click Create and open.
      2. In the Token validation section, in the Token processing profile field, press the Down arrow key and select the JSON Web Token profile that you created to validate the token.
      3. In the Operator identification section, select mapping the operator ID from either Standard subject (sub) claim or Custom claim.
        • If you select Custom claim, enter an expression to indicate the claim.
        • Indicate concatenation with a plus sign ("+"). Do not use @concat.
        • The value that you enter relates to the claims mapping in the processing token profile. For example, if you enter a Token processing profile value of DemoJWT and you enter a Custom claim value of {test}, then in the token profile instance for DemoJWT, you map the Claim name of test to a property on a clipboard page.
      4. In the Processing options section, in the Post processing activity field, press the Down arrow key and select the pyJWTBearerIdentityMappingAct activity that processes the JSON Web Token.
      5. Modify the pyJWTBearerIdentityMappingAct activity to map the claims in the Claim mapping and Advanced mapping section in the token profile to the operator page.
    • Custom – Select to map operator attributes from a custom source.
      CAUTION:
      For external users, modify steps 3, 4, and 5 in the pyCustomIdentityMappingAct activity. In addition, you must populate the pyOperPage parameter if it is not populated in the custom activity.
      1. Click Create and open.
      2. In the Processing options section, in the Post processing activity field, press the Down arrow key and select the activity name that is used to identify the operator through the password credentials.
  6. Click Save.