Skip to end of metadata
Go to start of metadata

This topic provides instructions on how to configure the MePIN app and the Identity Server to integrate using a sample app.

This is tested for the MePIN API version 3.0.

See the following sections for more information.

Configuring the MePIN app

  1. Install Android or IOS application on your mobile device.
  2. Log in to MePIN developer portal using your app.
  3. Get your application identifier and credentials. 

    1. Edit your organization.
    2. Create an application by providing the app name and domain name and get the appId / clientId.
    3. Create credentials (username and password).

  4. Contact MePin support to activate the application identifier. 

Deploying MePIN artifacts

  1. Place the mepinauthenticationendpoint.war file into the <IS_HOME>/repository/deployment/server/webapps directory.
  2. Place the org.wso2.carbon.identity.authenticator.mepin-2.0.0.jar file into the <IS_HOME>/repository/components/dropins directory.

    If you want to upgrade the MePIN Authenticator in your existing IS pack, please refer upgrade instructions.

  3. Add the following configurations in the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the <AuthenticatorConfigs> section.

    <AuthenticatorConfig name="MePINAuthenticator" enabled="true">
    	      <Parameter name="MepinAuthenticationEndpointURL">https://localhost:9443/mepinauthenticationendpoint/mepin.jsp</Parameter>
    	      <Parameter name="MepinAuthenticationEndpointErrorPage">https://localhost:9443/mepinauthenticationendpoint/mepinError.jsp</Parameter>
    	      <Parameter name="MepinEnableByUserClaim">false</Parameter>
    	      <Parameter name="MepinMandatory">true</Parameter>
    	      <Parameter name="usecase">association</Parameter>
    	      <Parameter name="secondaryUserstore">primary</Parameter>

    The following table includes the definition of the parameters and the various values you can configure.

    The mepin page which shows in the flows such as link with mepin and login with mepin.
    The mepin error page will be shown if there is issue in the authentication flow.
    This field makes it possible to disable the 'Mepin disabling by user' functionality. The value can be true or false. If the value is true, user can enable and disable the Mepin according to admin selection (MepinMandatory parameter value).
    If the value is true, the second step will be enabled by the admin. The user cannot be authenticated without Mepin authentication. This parameter is used for both super tenant and tenant in the configuration. The value can be true or false.
    usecaseThis field can take one of the following values: local, association, userAttribute, subjectUri. If you do not specify any usecase, the default value is local. See below for more details.

    The user store configuration is maintained per tenant as comma separated values. For example, <Parameter name="secondaryUserstore">jdbc, abc, xyz</Parameter>.  

    An admin can change the priority of the Mepin authenticator by changing the MepinMandatory value (true or false). 

    • If Admin specify that Mepin is mandatory (<Parameter name="MepinMandatory">true</Parameter> , then you must enable Mepin in the user’s profile by adding claim value true in order to authenticate the user. If this is not done, the Mepin error page appears. 
    • If Admin specify that Mepin is optional (<Parameter name="MepinMandatory">false</Parameter> and you enable Mepin in the user's profile, then the authenticator will allow the user to login with Mepin authentication as a second step (multi-step authentication). If Admin specify that Mepin is optional and you do not enable Mepin in the user's profile, the Mepin authenticator will proceed to log the user in as the first step (basic authentication).         

    The first step may be local authenticator (basic) or a federated authenticator (e.g., Facebook, Twitter, etc.). In federated authenticator support in first step, the following parameters are used according to the scenario. 

         <Parameter name="usecase">association</Parameter>
         <Parameter name="secondaryUserstore">jdbc</Parameter>
    usecase value can be local, association, userAttribute or subjectUri.

    This is based on the federated username. This is the default. You must set the federated username in the local userstore. Basically, the federated username must be the same as the local username.


    The federated username must be associated with the local account in advance in the Dashboard. So the local username is retrieved from the association. To associate the user, log into the end user dashboard and go to Associated Account by clicking View details.


    The name of the  federated authenticator's user attribute. That is, the local user name which is contained in a federated user's attribute. When using this, add the following parameter under the <AuthenticatorConfig name="MePINAuthenticator" enabled="true">  section in the <IS_HOME>/repository/conf/identity/application-authentication.xml file and put the value (e.g., email, screen_name, id, etc.).

    <Parameter name="userAttribute">email</Parameter>

    If you use, OpenID Connect supported authenticators such as LinkedIn, Foursquare, etc., or in the case of multiple social login options as the first step and Mepin as second step, you need to add similar configuration for the specific authenticator in the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the <AuthenticatorConfigs> section as follows (the following shows the configuration for Foursquare,LinkedIn and Facebook authenticator respectively).

    Inside the AuthenticatorConfig (i.e., Foursquare), add the specific userAttribute with a prefix of the (current step) authenticator name (i.e., MePINAuthenticator-userAttribute).

    <AuthenticatorConfig name="Foursquare" enabled="true">
           <Parameter name="MePINAuthenticator-userAttribute">http://wso2.org/foursquare/claims/email</Parameter>
    <AuthenticatorConfig name="LinkedIn" enabled="true">
       <Parameter name="MePINAuthenticator-userAttribute">http://wso2.org/linkedin/claims/emailAddress</Parameter>
    <AuthenticatorConfig name="FacebookAuthenticator" enabled="true">
    	<Parameter name="MePINAuthenticator-userAttribute">email</Parameter>

    Likewise, you can add the AuthenticatorConfig for Amazon,Google,Twitter and Instagram with relevant values.


    When configuring the federated authenticator, select the attribute in the subject identifier under the service provider section in UI, this is used as the username of the Mepin authenticator.

    If you use the secondary userstore, enter all the userstore values for the particular tenant as comma separated values. 

    The user store configuration is maintained per tenant:

    • If you use a super tenant, put all the parameter values into the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the AuthenticatorConfigs section.
    • If you use a tenant, upload the same XML file (application-authentication.xml) into a specific registry location (/_system/governance/MePINAuthenticator). Create the collection named Mepin, add the resource and upload the application-authentication.xml file into the registry). While doing the authentication, first it checks whether there is an XML file uploaded to the registry. If that is so, it reads it from the registry but does not take the local file. If there is no file in the registry, then it only takes the property values from the local file. This is how the userstore configuration is maintained per tenant. You can use the registry or local file to get the property values.

    4. Add the user claim http://wso2.org/claims/identity/mepinid. This is a mandatory claim in Mepin authentication. The claim configuration shows under Configuring User Claim section.

Deploying travelocity.com sample app

The next step is to deploy the sample app in order to use it in this scenario.

Once this is done, the next step is to configure the WSO2 Identity Server by adding an identity provider and service provider.

Configuring the identity provider

Now you have to configure WSO2 Identity Server by adding a new identity provider.

  1. Download the WSO2 Identity Server from here and run it.
  2. Log in to the management console as an administrator.
  3. In the Identity Providers section under the Main tab of the management console, click Add.
  4. Give a suitable name as the Identity Provider Name.

  5. Go to MePIN Configuration under Federated Authenticators . 

  6. Enter the values as given in the above figure.

    • Username: The username that you have generated from MePIN Developer Portal.
    • Password: The password that you have generated from MePIN Developer Portal.
    • Application Id: The application id that you have received from MePIN Developer Portal.
    • Callback URLService Provider's URL where the transaction status callback is sent when the user has reacted to the push notification.
    • Client Id: The Service Provider's pre-configured application-specific identifier.
    • Confirmation PolicyThe method required from the end user to confirm the  transaction (e.g., tap, pin, swipe, fp).
    • Expiry Time: Expiry time in seconds.
    • Header: Header message to be displayed by the MePIN Device App.
    • Message: Message to be displayed once the App is launched.
    • Short Message: Short message to display for push notifications.
  7. Select both checkboxes to Enable MePIN Authenticator and make it the Default.

  8. Click Register.

You have now added the identity provider.

Configuring the service provider

The next step is to configure the service provider.

  1. Return to the management console.

  2. In the Service Providers section under the Main tab, click Add.

  3. Since you are using travelocity as the sample, enter travelocity.com in the Service Provider Name text box and click Register .

  4. In the Inbound Authentication Configuration section, click Configure under the SAML2 Web SSO Configuration section.

  5. Now set the configuration as follows:

    1. Issuer: travelocity.com

    2. Assertion Consumer URLhttp://localhost:8080/travelocity.com/home.jsp

  6. Select the following check-boxes:
    1. Enable Response Signing.

    2. Enable Single Logout.

    3. Enable Attribute Profile.

    4. Include Attributes in the Response Always.

  7. Click Update to save the changes. Now you will be sent back to the Service Providers page.

  8. Go to Local and Outbound Authentication Configuration section.

  9. Select the Advanced configuration radio button option.

  10. Using the available drop-down list, add the basic authentication as the first step and MePIN authentication as the second step and click Update to save the changes.

You have now added and configured the service provider.

Configuring User Claim

  1. On the Main tab in the Management Console, click List under Users and Roles.
  2. Click Users. This link is only visible to users with the Admin role.
  3. From the list of users that appear in the resulting page, identify the user whose attributes you want to modify and click User Profile.
  4. In the Main menu, click Add under Claims.
  5. Click Add New Claim.
  6. Select the Dialect from the drop down provided and enter the required information.
  7. Add the user claim http://wso2.org/claims/identity/mepinid as following under 'http://wso2.org/claims'. This claim is mandatory for mepin authentication.

  8. Add the user claim http://wso2.org/claims/identity/mepin_disabled as following under 'http://wso2.org/claims'.

Testing the sample

  1. To test the sample, go to the following URL: http://<TOMCAT_HOST>:<TOMCAT_PORT>/travelocity.com/index.jsp   E.g: http://localhost:8080/travelocity.com

  2. Click the link to log in with SAML from WSO2 Identity Server.

  3. The basic authentication page appears. Use your username and password to log in.
  4. If you are enrolling for the first time, then you are directed to MePIN authentication page as shown below.
  5. Once you hit the Link MePIN button, you will be shown a MePIN login dialogue. Enter there your app’s nickname and get a random access code. Enter or scan the given access code to your app and finally confirm the linking.
  6. If the linking succeeds, you will be taken to the home page of the travelocity.com app. After that, your MePIN app has been linked to the service and can be used for secure login.
  7. If you are already linked, you will be directed to MePIN authentication page like below. You need to click "Login with MePIN".

  8.  Once you confirmed the login through your app, you will be taken to the home page of the travelocity.com app.
    • For the confirmation policy - swipe you will be prompted to confirm as follows
    • For the confirmation policy - tap you will be prompted to confirm as follows
    • For the confirmation policy - pin you will be prompted to confirm as follows
    • For the confirmation policy - fingerprint you will be prompted to confirm as follows

  • No labels