Identity proofing standalone

Introduction

IBM Security Verify has the ability to integrate with an OIDC based identity proofing vendor to add this functionality to external applications. This allows customers to integrate identity proofing into their own applications for any purpose. This is a more flexible option that requires a more hands on approach to identity proofing by relying on external development efforts.

Pre-requisites

An account with an OIDC based identity proofing vendor.
The OIDC connection credentials and endpoints.
- Client ID
- Secret
- Metadata URL
- Issuer
- Authorization endpoint
- Token endpoint
- etc.
An IBM Security Verify tenant

Configure OIDC provider

In the Verify Admin UI, navigate in the right panel to Integrations and then select OIDC providers.

Select Create OIDC provider. In the configuration tile, enter a name for the integration in the OIDC provider name field. Optionally you can add contact information. Select Next in the bottom right.

On the next page, enter all of the OIDC connection credentials, endpoints, and other information you have about the provider.

Select Create in the bottom right to finish creating the provider integration on the tenant.

Configure identity proofing flow

In the Verify Admin UI, navigate in the right panel to User experience and then select Identity proofing.

Select Create flow. In the configuration tile, enter a name for the flow in the Name field and optionally change the URL path. Set the Primary language. Enabling the setting Include attributes collection step adds a page to the identity proofing flow that will collect attributes. Enabling the setting Send attributes to third party will take attributes and send them to the identity proofing vendor. Select the Theme that will be used for this flow.

Scroll to the Configuration section. The Type will be oidc. Select the Integration id that was created in the Configure OIDC provider section. For security, you should enable Signed in the Login configuration section. In the Identity assurance configuration section, select the desired Claims request type. Optionally, select the desired Requested verified claims.

Scroll to the Outgoing attribute mapping section. This section is where you can configure outgoing attributes that map to an identity proofing vendor's input as a login_hint query string parameter. This is written in Verify scripted rules so transform the attributes that IBM Security Verify knows about to the ones that the vendor uses.

Example:

statements:  
    - context: fname := idsuser["given_name"]  
    - context: lname := idsuser["family_name"]  
    - context: telephone := idsuser["mobile_number"]  
    - context: email := idsuser["email"]  
    - context: credential := idsuser["credential"]  
    - context: dialCode := "1"  
    - context: output := "{"  
    - if:
        match: context.fname != ""
        block:        
            - context: output = context.output + "'fname':'" + context.fname + "',"  
            - if:      
                match: context.lname != ""      
                block:        
                    - context: output = context.output + "'lname':'" + context.lname + "',"  
            - if:      
                match: context.telephone != ""      
                block:        
                    - context: output = context.output + "'telephone':'" + context.telephone + "',"  
            - if:      
                match: context.email != ""      
                block:        
                    - context: output = context.output + "'email':'" + context.email + "',"  
            - if:      
                match: context.credential != ""      
                block:        
                    - context: output = context.output + "'credential':'" + context.credential + "',"  
            - if:      
                match: context.dialCode != ""      
                block:        
                    - context: output = context.output + "'dialCode':'" + context.dialCode + "',"  
            - context: output = context.output.substring(0,context.output.size()-1)  
            - context: output = context.output + "}"  
            - return: context.output

There is also a section below this where you can test your transformation before deploying.

The next section is the Response attribute mapping. Here you configure the response attribute mapping that converts the incoming values from an identity proofing vendor to an easier to read format for IBM Security Verify. It is configured similar to the Outgoing attribute mapping.

The section below this is the Decision mapping, where you map the overall decision from the identity proofing flow by pulling the value from the expected vendor response. Allowed values are approve, deny, or obligate.

The final section is for Human verification, where you would optionally configure reCAPTCHA for the flow. You can now click Start building flow in the bottom right.

Now it is time to start building the look and feel of the flow. You can add attributes for collection, change text, and translations at this time. Once you are done making modifications, save the flow by clicking Save changes in the bottom right and we will publish the flow by clicking Publish in the top right.

Before we can use this page, it needs to be integrated into an application that can view and process the results and the vendor needs to be aware of the redirect url.

Register redirect url

This step will vary depending on your OIDC identity proofing vendor. In the vendors config, there will be a place to add valid redirect urls. In this you should add the url of the identity proofing flow you configured in the previous step.

Example: https://idproofing.verify.ibm.com/profile/v3.0/flows/identity_proofing/test-identity-proofing

Configure an application integration

In the application with which you want to integrate identity prooing, add an invocation to redirect to your identity proofing flow. This should include the callback_url query string parameter so that the flow knows where to come back to on completion.

For example

<Button href="https://idproofing.verify.ibm.com/profile/v3.0/flows/identity_proofing/identity-proofing-test?callback_url=https%3A%2F%2Fapp.example.com%2F%23%2Fidentity-proofing-response" type="button">Prove Identity</Button>

This will kick off the flow, but you will need to configure your server to make a request to the results API on return. Have your server call the below API:

"https://idproofing.verify.ibm.com/profile/v3.0/flows/identity_proofing/identity-proofing-test/results/" + resultsId;

The results ID will be a query string parameter that is returned from calling the identity proofing flow.

The response will have three parts based on the Verify scripted rules that were written for the Response attribute mapping.

{
    "decision": "approve",
    "vendorResponse": {
        // raw vendor response here
    },
    "processedAttributeMapping": {
        // Verify scripted rules transformed vendor response
    }
}

Depending on the vendor and Verify scripted rules transform, you may want to process different data in your application. The top level decision from the Verify scripted rules Decision mapping is also displayed for quick processing.

Try it out

Give this a shot by going to the registration url that you configured in the previous step.

Example: https://idproofing.verify.ibm.com/register/register-and-prove-identity

Start at the registration page.

Which will direct you to the identity proofing page.

Which will redirect you to a page informing you that you are going to be sent to a third party for identity proofing.

Complete the steps on the identity proofing vendor where you will be redirected back to IBM Security Verify and can continue with the registration process.