ID for Identity Providers Reference Implementation

Table of Contents

• Overview
  • References
• Usage
  • Prerequisites
  • Configuration
  • Integrating with OpenAPI Generator
  • OpenAPI Generator Plugin Configuration
  • Generating The API Client Sources
  • Build the Project
  • Test Case Execution
  • Use Cases
  • Execute the Use-Cases
• API Reference
  • Authorization
  • Request Examples
  • Client Encryption
  • Recommendation
• Support
• License

Overview

ID is a digital identity service from Mastercard that helps you apply for, enroll in, log in to, and access services more simply, securely and privately. Rather than manually providing your information when you are trying to complete tasks online or in apps, ID enables you to share your verified information automatically, more securely, and with your consent and control. ID also enables you to do away with passwords and protects your personal information. Please see here for more details on the API: Mastercard Developers.

For more information regarding the program, refer to ID Service

References

• Mastercard's OAuth Signer library
• Using OAuth 1.0a to Access Mastercard APIs
• Mastercard's Payload Encryption/Decryption library
• Using Payload Encryption

Usage

Prerequisites

• Mastercard Developers Account with access to ID for Identity Providers API
• IntelliJ IDEA (or any other IDE)
• Spring Boot 2.2+ up to 2.7.x
• Apache Maven 3.3+
• Java 8
• Set up the JAVA_HOME environment variable to match the location of your Java installation

Configuration

1. Create an account at Mastercard Developers.
2. Create a new project and add ID for Identity Providers API to your project.
3. Download Sandbox Signing Key, a .p12 file will be downloaded.
4. In the Client Encryption Keys section of the dashboard, click on the 'Actions' dropdown and download the client encryption key, a .pem file will be downloaded.
5. Select all .p12 and .pem files, and copy them to src/main/resources in the project folder.
6. Open ${project.basedir}/src/main/resources/application.properties and configure below parameters.

mastercard.api.base.path= This base path, will be used as a host to make API calls. Change it corresponding to MC ID Service Url. For example https://developer.mastercard.com/mastercard-id-for-idp/documentation/.

idp.userIdentifier= This is the unique identifier which IDP provides upon authenticating an end-user. This value forms 'alias' claim in the JWT token to be generated by IDP while invoking Mastercard's IDP API endpoints. For more information on this unique identifier please refer at Mastercard IDP API Reference app usage.

server.port= Application Port.

Authentication

mastercard.api.key.file= This refers to .p12 file found in the signing key. Please place .p12 file at src\main\resources in the project folder and add classpath for .p12 file.

mastercard.api.consumer.key= This refers to your consumer key. Copy it from "Keys" section on your project page in Mastercard Developers

mastercard.api.keystore.alias= Alias of your key. Default key alias for sandbox is keyalias.

mastercard.api.keystore.password= Password of your Keystore. Default keystore password for sandbox project is keystorepassword.

Encryption

mastercard.client.encryption.enable= This parameter allows to encrypt the payload before send it to the server in case it's true.

mastercard.api.encryption.certificateFile= It contains the reference for the pem file certificate used by the client to encrypt payload, this file should be located at src/main/resources.

mastercard.api.encryption.fingerPrint= The fingerprint of the Mastercard public key used to encrypt the ephemeral AES key. more information please refer at Issuer-Initiated Tokenization.

Decryption

mastercard.client.decryption.enable= This parameter allows to decrypt the payload.

mastercard.api.decryption.keystore= This is the password provided while creating the API project in Mastercard Developers.

mastercard.api.decryption.alias= This is the keyalias user provided, that is used while creating the API project in Mastercard Developers.

mastercard.api.decryption.keystore.password= This is the keyalias password provided, that is used while creating the API project in Mastercard Developers.

Integrating with OpenAPI Generator

OpenAPI Generator generates API client libraries from OpenAPI Specs. It provides generators and library templates for supporting multiple languages and frameworks.

See also:

• OpenAPI Generator (maven Plugin)
• OpenAPI Generator (executable)
• CONFIG OPTIONS for java

OpenAPI Generator Plugin Configuration

<!-- https://mvnrepository.com/artifact/org.openapitools/openapi-generator-maven-plugin -->
<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>${openapi-generator.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/mastercard-idservice-reference_api_spec.yaml</inputSpec>
                <generatorName>java</generatorName>
                <library>okhttp-gson</library>
                <generateApiTests>false</generateApiTests>
                <generateModelTests>false</generateModelTests>
                <configOptions>
                    <sourceFolder>src/gen/main/java</sourceFolder>
                    <dateLibrary>java8</dateLibrary>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Generating The API Client Sources

Now that you have all the required dependencies, you can generate the sources. To do this, use one of the following two methods:

Using IDE

• Method 1
  In IntelliJ IDEA, open the Maven window (View > Tool Windows > Maven). Click the icons Reimport All Maven Projects and Generate Sources and Update Folders for All Projects

• Method 2
  

  In the same menu, navigate to the commands ({Project name} > Lifecycle), select clean and compile, then click the icon Run Maven Build.

Using Terminal

• Navigate to the project's root directory within a terminal window and execute mvn clean compile command.

Build the Project

Once you clone the project you must ensure that IntelliJ IDEA recognizes the folders. Go to (file > project structure > modules) and select the folder src/main/java as a source and src/test/java as test folder, also check the language level at this configuration options and see if it's selected (8 - lambda type annotation etc.) following your java version add also the Maven support in the Project tool window, right-click your project and select Add Framework Support.

Test Case Execution

Navigate to the test package and right click to Run All Tests

Use cases

1. RP Scopes
   • Retrieve the scopes and RP details associated with the arid. The ARID must be in PENDING status.
2. Scope fulfillments
   • Process the IDP claims and update the authentication request with the claims data.

More details can be found here.

Guides and tutorials can be found here.

Execute the Use-Cases

1. Run mvn clean install from the root of the project directory.
2. There are two ways to execute the user cases :
   1. Execute the test cases
      • At the src/test/java which is the main root folder for all Junit tests of the application.
      • Run the tests.
   2. Select the menu options provided by the application
      • Run mvn spring-boot:run command to run the application.
      • Once the application is running, you should be able to see and chose the follow three options :
        • 0 Exit
        • 1 RP Scopes
        • 2 Scope-fulfillments
      • The option 1 and 2 are going to ask for the ARID value in case you press enter the ARID value used is going to be the one found at the application.properties file.

API Reference

To develop a client application that consumes the ID for Identity Providers API with Spring Boot, refer to the ID for Identity Providers Reference.

Authorization

The com.mastercard.dis.mids.reference.config package will provide you API client. This class will take care of adding the correct Authorization header before sending the request.

Request Examples

You can change the default input passed to APIs, modifying values in the following file: com.mastercard.dis.mids.reference.constants.Constants

Client Encryption

The public key your application uses to encrypt requests is listed under “Client Encryption Keys” on the Developer Dashboard. this key file is linked at the application.properties. for more information please go to Payload Encryption. We also recommend reading Using Payload Encryption link at the References section at this document.

Recommendation

It is recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Support

If you would like further information, please send an email to apisupport@mastercard.com

• For information regarding licensing, refer to the LICENSE.
• For copyright information, refer to the COPYRIGHT.
• For instructions on how to contribute to this project, refer to the CONTRIBUTING.
• For changelog information, refer to the CHANGELOG.

License

Copyright 2023 Mastercard

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.