Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Access Management
11g Release 2 (11.1.2)

Part Number E27134-03
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

10 Developing Applications Using the Internet Identity Services Client SDK

This chapter describes how to use the Internet Identity Services Client SDK to integrate Mobile and Social with supported web and mobile applications. This chapter includes the following topics:

10.1 Before you Begin

Before reading this chapter you should read "Understanding Mobile and Social" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management. This Developer's Guide assumes that you are already familiar with and understand Mobile and Social terminology and concepts.

10.2 Introduction to Developing Internet Identity Services Applications

This section covers concepts and requirements that apply to Internet Identity Services application development in general.

Internet Identity Services supports the following integration scenarios:

Mobile and Social features a prebuilt login page for Internet Identity Services. This page supports local authentication so that users with existing accounts can log in and it provides Internet Identity Provider support so that new or existing users can authenticate using an Internet Identity Provider, such as Yahoo, Google, Facebook, LinkedIn, and Twitter. You can use the prebuilt login page for both local user authentication and Internet Identity Provider authentication, or you can choose to use the Mobile and Social login page for Internet Identity provider authentication only, while keeping the web application's local user authentication mechanism in place. The look and feel of the prebuilt login page can be customized as needed.

To facilitate the creation of end-user accounts, end-users who authenticate using an Internet Identity Provider can be prompted to create a local account. Mobile and Social retrieves the end-user's profile from the Identity Provider, and built-in user registration functionality will pre-populate the user's data.

Note:

OAuth providers such as Facebook, Twitter, and LinkedIn require that applications register each Mobile and Social instance to get the consumer key and secret values.

10.2.1 About the Internet Identity Services Client SDK

The primary Java package that you will use when working with the Internet Identity Services Client SDK is the oracle.security.idaas.rp.client package. (The "rp" stands for relying party.)

In addition, the following libraries are required to be available during the compilation and execution phases. These libraries must also be available in the class path of the application server when the client code is included in a web application that may be compiled at run time by the web container. These libraries are provided in the product package, oamms_sdk_for_java.zip.

The following libraries are included in oamms_sdk_for_java.zip, as well as license information and API documentation.

Mobile and Social Libraries

  • oic_clientsdk.jar

  • oic_common.jar

  • oic_sae.jar

  • ojdl.jar

Third-Party Archives

  • jersey-archive-1.9.1

10.3 Getting the List of Identity Providers for an Application

The RPClient class located in the oracle.security.idaas.rp.client package is required to get the list of configured Internet Identity Providers for an application.

The RPClient class takes two parameters: applicationID and properties.

The first parameter, applicationID, is a unique identifier that identifies the application. This String value must match the application "Name" value located in the Application Profile section of the Mobile and Social server administration console. For more information, see the "Configuring Internet Identity Services" chapter in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

The second parameter is a URI that maps to a properties file. This properties file lists the configuration properties that the application and the Mobile and Social server require to connect and securely exchange data. The properties file must be in a location that is accessible to the application at run time.

The following table lists the required and optional configuration properties that the Mobile and Social server accepts. All properties are Strings and, unless otherwise noted, are optional.

Table 10-1 Configuration Properties Required by the RPClient Class

Property Name Required Description Comment

rp.server.hosturl

Required

The URL (including protocol, host name, and port number) required to reach the Mobile and Social server. Only the HTTP and HTTPS protocols are supported.

 

rp.server.idp.service

Required

The relative path required to reach the identity providers service.

The current service path is:

/oic_rp/rest/
identityproviders

This path is appended to the rp.server.hosturl property.

rp.server.init.service

Required

The relative path required to reach the Relying Party (RP) service.

The current service path is:

/oic_rp/
RPInitServlet

rp.server.connection.timeout

 

The duration in milliseconds after which the connection is interrupted if the server stops responding. Null or empty means infinite (no time-out).

 

rp.server.connection.sae.sharedsecret

Required

The secret used to secure communication with the server.

Base64 encoded String.

rp.server.connection.sae.algorithm

 

The algorithm used to secure communication with the server. Defaults to SAE if omitted.

Supported values include:

SAE - Secured Attribute Exchange.

DES - Data Encryption Standard.

rp.server.connection.sae.keystrength

 

The key length used to encrypt the key. Defaults to 128 if omitted.

 

rp.server.connection.sae.cryptotype

 

The type of cryptography. Defaults to symmetric if omitted.

 

rp.server.connection.sae.keystorefile

 

The file name containing the encryption keys.

 

rp.server.connection.sae.keystoretype

 

Determines the type of keystore.

 

rp.server.connection.sae.keystorepass

 

The keystore password.

 

rp.server.connection.sae.privatekeyalias

 

The private key alias.

 

rp.server.connection.sae.publickeyalias

 

The public key alias.

 

rp.server.connection.sae.privatekeypass

 

The private key password.

 

rp.server.connection.sae.certclass

 

The class name implementing the Cert interface.

 

proxy.protocol

 

The protocol to use with a proxy server.

Supported values include:

http

socks

direct

proxy.host

 

The host name of the proxy server.

 

proxy.port

 

The proxy server port number.

 

proxy.username

 

The user name required to authenticate with the proxy server.

 

proxy.password

 

The password required to authenticate with the proxy server.

 

The following sample code consists of a single class that outputs the available Internet Identity Providers and their corresponding URLs. You can use this code to verify an Internet Identity Service platform configuration. Simply provide the required applicationId input parameter.

First, import the following class dependencies:

// Java imports
import java.io.BufferedWriter;
import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.net.MalformedURLException;
 
// Mobile and Social imports
import oracle.security.idaas.rp.client.RPClient;
import oracle.security.idaas.rp.client.RPClientConfigUtil;
import oracle.security.idaas.rp.client.RPClientException;

Next define the following constants:

public class SampleOicClient {
    // Define the default properties file name
    private static final String PROP_FILE_NAME = "SampleOicClient.properties";
    // Pre-define the Client SDK properties
    private final static String PEOPLE_SERVICE = "/oic_rest/rest/userprofileservice/people";
    private final static String TOKEN_SERVICE = "/oic_rest/rest/tokenservice1/tokens";

The createPropertiesFile() function creates a default properties file if a local file is not found. You still need to provide the required values, however. Refer to Table 10-1 for details.

private static void createPropertiesFile() {
        try {
 
            // Create file 
            FileWriter fstream = new FileWriter(PROP_FILE_NAME);
            BufferedWriter out = new BufferedWriter(fstream);
            out.write("");
            out.write("rp.server.hosturl=http://hostcomputer.example.com:18001\n");
            out.write("rp.server.idp.service=/oic_rp/rest/identityproviders\n");
            out.write("rp.server.init.service=/oic_rp/RPInitServlet\n");
 
            out.write("rp.server.connection.timeout=60000\n");
            out.write("rp.server.connection.sae.sharedsecret=sharedSecret1\n");
            out.write("rp.server.connection.sae.algorithm=AES\n");
            out.write("rp.server.connection.sae.keystrength=128\n");
            out.write("rp.server.connection.sae.cryptotype=symmetric\n");
            out.write("rp.server.connection.sae.keystorefile=\n");
            out.write("rp.server.connection.sae.keystoretype=\n");
            out.write("rp.server.connection.sae.keystorepass=\n");
            out.write("rp.server.connection.sae.privatekeyalias=\n");
            out.write("rp.server.connection.sae.publickeyalias=\n");
            out.write("rp.server.connection.sae.privatekeypass=\n");
            out.write("rp.server.connection.sae.sigvalidityduration=\n");
            out.write("rp.server.connection.sae.certclass=\n");
 
            out.write("#proxy configuration\n");
            out.write("proxy.host=\n");
            out.write("proxy.port=\n");
            out.write("#http|socks|direct\n");
            out.write("proxy.protocol=\n");
            out.write("proxy.username=\n");
            out.write("proxy.password=\n");
 
            out.close();
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }

The following code outputs the available Internet Identity Providers based on the required applicationID identifier provided.

public static void main(String[] args) {
        RPClient client = null;
        int exitStatus = 0;
        String ret = null;
        File prop = new File(PROP_FILE_NAME);
        String applicationName = null;

        //Check the arguments: applicationID is mandatory
        if (args.length < 1 || args[0].isEmpty()) {
            System.err.println("Invalid number of arguments. Specify the name of the application 
(the applicationID) to be used to connect to the Mobile and Social Server.\n");
            exitStatus = 1;
        } else {
            applicationName = args[0];

            // Check if a properties file is available
            if (prop.exists()) {
                RPClientConfigUtil conf = null;

                // Read the configuration using the provided utility class
                try {
                    conf = new RPClientConfigUtil(prop.toURI().toURL());
                } catch (MalformedURLException e) {
                    System.err.println("Malformed URL:" + e.getMessage());
                    exitStatus = 1;
                } catch (IOException ioe) {
                    System.err.println("IO Exception:" + ioe.getMessage());
                    exitStatus = 1;
                }
                System.out.println("RPClient :\n=========\n");
                try {

                    // Initiate the interface with the Mobile and Social Server using 
                    // the configuration properties and the applicationID.
                    client = new RPClient(applicationName, conf);
                    
                    ret = "The application name is [" + applicationName + "]\n";
                    ret += "The retrieved IDP information is:\n\n";
                    for (String idp : client.getIDPList()) {
                        // Display the IDP name
                    ret += "    IDP name : " + idp + "\n";
                        // DISPLAY the IDP reference URL
                    ret += "    IDP Href : " + client.getHrefByIdpName(idp);
                        ret += "\n";
                    }
                } catch (RPClientException rpce) {
                    System.err.println("Client Exception:" + rpce.getMessage());
                    exitStatus = 1;
                }
                System.out.println(ret);
                System.out.println("\nClient SDK :\n============\n");
                System.out.println("    CreateToken :\n    =============\n");
                new CreateToken(conf.get("rp.server.hosturl") + TOKEN_SERVICE);
                System.out.println("\n    People :\n    ========\n");
                new CreateUser(conf.get("rp.server.hosturl") + PEOPLE_SERVICE);
            } else {
                //No properties file is available, so create a default one
                createPropertiesFile();
                System.out.println("The " + PROP_FILE_NAME + " properties file has not been found.
 A default one has been created at this location.");
                System.out.println("Please edit the file and provide the required values. Then 
 restart this utility.\n");
                exitStatus = 2;
            }
        }
        System.exit(exitStatus);
    }
}

10.4 Integrating Internet Identity Services With a Web Application Running on a Server

The Internet Identity Services SDK supports web applications, such as portal sites and consumer-driven web sites that run on Java-compliant application servers.

To integrate Internet Identity Services with a web application, first define the web application on the Mobile and Social server, then integrate the Internet Identity Services login page with the web application. Next, configure User Registration (optional) and handle the final return response.

This section covers the following topics:

10.4.1 Defining the Web Application on the Mobile and Social Server

Use the Mobile and Social system administration console to define the web application on the Mobile and Social server. See "Editing or Creating Application Profiles" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management for help completing this task.

Following is a brief description of some of the items that you need to configure on the Mobile and Social server:

  • Application Name - Provide the context name of the web application.

  • Application Return URL - Provide the URL that Mobile and Social should use to send back authentication responses.

  • Shared Secret - Provide the security secret that the web application and the Mobile and Social server share to facilitate secure communication. The shared secret is also needed during User registration.

  • Required Identity Providers - Choose the Identity Providers that the end-user can pick from to authenticate to the application.

  • Application User Profile Attribute Mappings - Map the user profile attributes that the Identity Provider returns to the user profile attributes that are local to the application.

  • User Registration and Registration URL - Indicate if the system should prompt Users who do not have a local account to register. Provide the URL to which the server should redirect Users after authentication when the Service Provider completes.

10.4.2 Integrating the Internet Identity Services Login Page With the Web Application

To integrate Internet Identity Services, use the Internet Identity Services Client SDK (oic_clientssdk.jar) and modify its login page (login.jsp).

There are two ways that you can integrate the Internet Identity Services login page with a web application: (1) Add the pre-built login page hosted on the Mobile and Social server to the web application using the HTML <iframe> tag, or (2) Build a custom login page using Internet Identity provider data provided by Mobile and Social.

10.4.2.1 Adding the Pre-built Internet Identity Services Login Page

To add the login page hosted on the Mobile and Social server to the web application, first get a secure token using the SDK. The web application needs a Secured Attribute Exchange (SAE) token, which is based on the shared secret that is known to the web application and the Mobile and Social server.

The following sample code shows how to initialize the Internet Identity Service client SDK and get the saeToken. This code can be added to a JSP page, for example login.jsp.

The RPClient class takes two parameters: applicationID and properties.

RPClient rpClient = new RPClient(“sampleapp”,properties);
Map<String, String> attrs = new HashMap<String, String>();
attrs.put("applicationID",“sampleapp”);
String saeToken = rpClient.getSaeToken(attrs,properties.getProperty("rp.server.connection.sae.sharedsecret"),
properties.getProperty("rp.server.connection.sae.sharedsecret"));

The getSaeToken method gets the SAE token for the application.

The sae.sharedsecret property from the properties file makes up the second and third parameters of the rpClient.getSaeToken method. (For details, see Section 10.3, "Getting the List of Identity Providers for an Application.") The first instance of the "SAE secret" is used to sign the attributes, and the second instance is used to encrypt them. If the second instance of the "SAE secret" (that is, the third parameter of the method) is null, the attributes are signed but not encrypted.

Next, use an HTML <iframe> tag to embed the Internet Identity Service login page:

<iframe
src="http://oc.example.com:24666/oic_rp/login.jsp?applicationID=sampleapp&saeToken=<%=saeToken%>"
scrolling="no"
frameBorder="no"
allowtransparency="true"
style="width:720px;height:440px;">
</iframe>

The following screen capture shows a sample login screen that has used an iframe to integrate the prebuilt login page hosted on the Mobile and Social server. This page has been configured to support both local user authentication and Internet Identity Provider authentication.

Figure 10-1 Pre-built Login Screen With Local Login Support

Sample pre-built login screen.

The next screen capture shows the same page as the previous example with only Internet Identity Provider support enabled. In this example, the web application would implement its local user authentication mechanism separately.

Figure 10-2 Pre-built Login Screen Without Local Login Support

Sample pre-built login screen.

10.4.2.2 Building a Custom Login Page

If you need greater flexibility building your login page, use the approach outlined in this section.

The code in the following example initializes the Internet Identity Service client SDK, invokes the REST endpoint, gets the identity provider data, then builds the login page using an HTML table to display the Identity Provider logos in table rows.

String ret =” ";
RPClient client = null;
try { 
     client = new RPClient("sampleportal", "rpclient.properties");
     for (String idp: client.getIDPList()){
        ret += "\n<TR><TD><a href='" + client.getHrefByIdpName(idp)
                + "'><img src='images/" + idp.toLowerCase()
                + ".gif' alt=" + idp + " title=" + idp
                + "border='0'></img></a></TD></TR>";
}
} catch(Exception e){
      e.printStackTrace();
}

The output from the Mobile and Social server looks like this.

<table cellpadding="6" cellspacing="6" align="center">
<th colspan=2>Sign in with any Account</th>
<TR>

<td>
<a href='http://rp.example.com:24666/oic_rp/init?applicationID=sampleportal
&saeToken=RU5DUllQVEVENjIwODgxM0ZCNTAxOEZENUZBRTA2MzYxOTJBQzM3MDIwQjc5NEE1RDdFMjczREYxNUYw
Mzk0NjQwRjRFRTQwNzBCMzc0OEMyRUVENTkyOTVCMkI5NUU0MzM2QTk5MzYyRjJCQjg5MDJDNDcwNDlFNTFFMTIzMU
Q5OTY1RTZBMjA3QzM3N0FCNDlBMDlFQjVFQUI2RDlDRTU1RERGOTExNEIyMThFNzBGMjYzRkI3MkRGNEIwMjlENTBFQ
zFEMTM1RkUzRjU5RjcxQkMxQTg2QkNBNzAzQTUwOTBCRUJBOEY3REM5RUU3RjIyQjEwQ0Q5QzNCQjA0RDVDRDBGQUNF
NkM1M0ZGQzJCNDk4NERBRDNGNkI4REY0QkU3QzZCMDU4QTRBREQxNTI4NzdCMTkxRkU4MTdGRTYzNEQ0OTdFN0MxQzk
3M0MzQkFFOEVCQzEwQzg0NDIzMDQ1NDAyNUZCRQ=='><img src='images/facebook.gif' alt=Facebook
title=Facebook border='0'></img></a></td>
<td>
<a href='http://rp.example.com:24666/oic_rp/init?applicationID=sampleportal
&saeToken=RU5DUllQVEVENjIwODgxM0
xNUYwMzk0NjQwRjRFRTQwNzBCMzc0OEMyZCNTAxOEZENUZBRTA2MzYxOTJBQzM3MDIwQjc5NEE1RDdFMjczREYRUVENT
RUVENTkyOTVCMkI5NUU0MzM2QTk5MzYyOTM3REY0NzJFQTIzQTVDNDY4RjRCREJFRTM4OEU2RDI2QUI3QTc4QjE3RUNDO
DY4NDU2MDZCQjk4Q0IyNjg3QTNFMUQzOTVENTM5NjEzRTZDMTM3RjVBNDJFRUZENzUzOERDOEVDQkUzOEY5NEM5QjU2Qz
E4NjVGRTA2MzVCMDBBNUYyNTgzRDU0OEI4ODE4RUI4ODgxMkUyMEM3RDU3RUIwQjMyRTk2RkI3ODc5RkI1MzU5QjhFNDU1
RjZDQzZEQTlEQTVCRDkwQjIxQzEyRDUzNEIzNTMyNTgwRTZCOTM3NzZDM0UyNTg2QTE3MTZFMDc3MTJFNDAxMDI3OTg1Qw=='>
<img src='images/twitter.gif' alt=Twitter title=Twitter border='0'></img></a></td>
</TR><TR>
<td> 
<a href='http://rp.example.com:24666/oic_rp/init??applicationID=sampleportal
&saeToken=RU5DUllQVEVENjIwODgxM0ZCNTAxOEZENUZBRTA2MzYxOTJBQzM3MDIwQjc5NEE1RDdFMjczREYxNUYwMzk
0NjQwRjRFRTQwNzBCMzc0OEMyRUVENTkyOTVCMkI5NUU0MzM2QTk5MzYyNThGRDM1MjRDRDQ2QTQ5RTRFMEZEMTY3OEEyQ
TAxM0Y4NDQ1MjUwODkxRTlBRDgzMDdBNDRDRjEzMkE4MEJCNkU5ODhCMjcyRkNBNUMwREJFRjA4MDAzQkMwRTAzQzNGNkUy
OEJEMzMxMDcwNTlEMDdGQjREMzFEQjdCRjRDM0YxNUQ4OTI2QTY4OUM1NDIwNjk5MDY3RUM0M0YyNjA0QjBBRDc3MkZGOThB
QjUxRTJDQUFFOEYwOEQ0QTE3Njc4MDM1NjYxNzY5MzY4Mjk0MjVFRDFGNDhEMDAzQTFBMjU1MEQ1QUE1RkM3MkNDMUNGMjUwN0J
CMEI1NDkzM0Q5NQ=='><img src='images/linkedin.gif' alt=LinkedIn title=LinkedIn border='0'></img>
</a></td>
<td>
<a href='http://rp.example.com:24666/oic_rp/init??applicationID=sampleportal
&saeToken=RU5DUllQVEVEMDI5M0FFNjIzMEVEOUZEQkEzMEU0QzAxMDlCOTg1ODlDQ0I5QkQxM0JGQjhGQkY5QzAzNDZER
EZGN0I1RDBBMjQ3NzkxNjdBOERFNTUzN0IxMzk0QTdENUUyNDQxOTdBNkE4MDEwOTlGOEJDNTIyQTQwMEU3OTM3OUUxQTRFR
UYyNjY0MDc3Nzc0OEMzNDJCMzhCOUJDREZBQzdCNENFQkI5NTBCNDRCOTQyQjU5NkYwMEQ2MUY3MUMxNkJEOUIyQzk5MTk1R
DRGNzQ4OTg0QzFDMjFEMzQwOUQ0RUIxQTRFOTZGMTFBN0ExODg3MTZCQTc5QUE2QTU5RDk3MUMzOUQ1MkY1NEM2Q0I1OUFCNz
FBOTQ3M0VBQkE3QzUzQzc0MzM4ODk3RUY3NEJFQkJFODg2QjE4QkU5RUFGQURFRDE3NUMyRTg0NjRDRjNDQzJGN0Y1QTU4RDlD
OTIzMDM5OQ=='><img src='images/google.gif' alt=Google title=Google border='0'></img></a></td>
</TR><TR>
<td>
<a href='http://rp.example.com:24666/oic_rp/init??applicationID=sampleportal
&saeToken=RU5DUllQVEVEMDI5M0FFNjIzMEVEOUZEQkEzMEU0QzAxMDlCOTg1ODlDQ0I5QkQxM0JGQjhGQkY5QzAzNDZEREZGN
0I1RDBBMjQ3NzkxNjdBOERFNTUzN0IxMzk0QTdENUUyNDQxOTdBMDQ5MjMxQUJDMUZDMzVFNjI5NkVBREZBNzk0MUJDQTY2OTE3
RkRCQTUyRUFERTVGNEIyN0NCMzMzMThBQTM2MDlGOTE5NDY4OTBCN0EyNzdGRUY2Qjc1RTBENjY4MDEyNTVGOTA3Mzc5MTZGQkU
1MkM0RkQwMEJFQjAzOUQ4NEQyOEYyNDU4MDRDMjUzQjg2ODlGRkM1MkFGRTEwOTAwMDM2NDExRDIwMzkyMDBBMzYxMkZGRjU4Rj
VNkFBQ0QwQTgyMzA2NDA2REEyMzkxMzU2NjAzNDIzNzE5MDdDM0RFRURGNTE5NjI4MzQ2RTVCNzZCOTg5Q0NFMkM2RTkwMQ=='>
<img src='images/yahoo.gif' alt=Yahoo title=Yahoo border='0'></img></a></td></TR>
<!-­--­-End Providers-­--­->
</table>

10.4.3 Handling User Registration

To facilitate the creation of local end-user accounts, Mobile and Social can prompt users to create a local account. After the User authenticates with an Identity Provider, Mobile and Social can redirect to a custom User registration page or to a built-in registration page that is included with the Mobile and Social Server.

This section covers both approaches:

10.4.3.1 Using a Custom User Registration Page

Use the information in this section to configure a custom User Registration Page for use with Mobile and Social.

Configure the User Registration Properties on the Server

Use the Mobile and Social system administration console to configure the following User Registration properties for the application:

  • User Registration (Choose "Enabled")

  • Registration URL

  • Attributes (Located in the "Application User Attribute" section)

  • Attribute Mapping (Located in the "Registration Service Details with Application User Attribute Mapping" section)

For information about each field, see "Editing or Creating Application Profiles" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

Decrypt the saeToken

If User Registration is enabled for the application, Mobile and Social redirects to the configured Registration URL. Mobile and Social does a POST to the URL and includes two parameters: saeToken, which contains the User profile data encrypted with the shared secret, and Application, which is the application name.

Use the RPClient API in the oic_clientsdk to decrypt the saeToken.

For example:

String saeToken = request.getParameter("saeToken");
Map<String, UserAttribute> regAttrMap = null;
if (saeToken != null) {    Map<String, String> saeAttrs = client.getAttrFromSaeToken(saeToken,
                                   ”shared secret value”,”shared secret value”);
    System.out.println("register: saeAttrs :" + saeAttrs);
        String regAttrs = saeAttrs.get ("reg_attrs");
    String selectedIDP = saeAttrs.get ("oicInternetIdentityProvider");
    String state = saeAttrs.get ("return_url");
}

The following block shows all of the attributes of saeToken:

saeAttrs :{readonly_fields=uid,mail, password_field=password,
registerReadOnlyToken=RU5DUllQVEVEODk4QjlGQzU0RjNDNTQyNTY0NTU1MzMzOTU3RDU3QjkwNzd
EMTBGREJDMTlBQjM4NDIzNTFFRkI0OUNDQjg1M0JFREQ1NTdCM0I5RkY4MEYyNjFDMEE1NUFBRjhDQjA4
QTQ1M0IyMDg0MzFCNzgxQjg4Nzg4QzJFNEU5MzJFNUM0MjgxMEQxNjEzNkFERjE1MUE0QTMzM0E3MTMyN
zM5NUExN0U3MzA2MjZCRjZDQzgxN0I2MjIwNzEyNEQ2REVE, 
reg_attrs=uid:UserId:example@gmail.com:,mail:Email Address::,
timezone:Time Zone::,postaladdress:Country:US:,preferredlanguage:Language:en-US:,
lastname:Last Name:doe:,commonname:First Name:john:,password:Password::,,
username_attr=uid, mandatory_fields=uid,mail,password,password,
state=f166f9aa12edaaeffce703276de2d73c30dbddd0,
oicInternetIdentityProvider=Google, 
return_url=http://host.example.com:18001/oic_rp/popup?state=f166f9aa12edaaeffce703276de2d73c30dbddd0}

The application needs to process the value of reg_attrs. The other saeToken attributes should be ignored.

reg_attrs=uid:UserId:example@gmail.com:,mail:Email Address::,
timezone:Time Zone::,postaladdress:Country:US:,preferredlanguage:Language:en-US:,
lastname:Last Name:doe:,commonname:First Name:john:,password:Password::,,

The value is a comma-separated {User Attribute Name:User Attribute Label:User Attribute Value} set.

The application can redirect to the Mobile and Social Return URL by appending oicUserRegister=done to the URL.

For example:

response.sendRedirect(http://oic.host.com:18001/oic_rp/popup?state=f166f9aa12edaaeffce703276de2d73c
30dbddd0&oicUserRegister=done);

Mobile and Social creates a User Token based on the Identity Provider authentication and returns it to the application.

10.4.3.2 Using the Mobile and Social Built-in User Registration Page

Use the information in this section to enable the built-in User Registration page. This page is shown in Figure 10-3.

Configure the User Registration Properties on the Server

Use the Mobile and Social system administration console to configure the following User Registration properties for the application:

  • User Registration (Choose Enabled)

  • Registration URL (Set to the URL provided with the default Mobile and Social Internet Identity Services application, OAMApplication. For example: http://host.example.com:port/oic_rp/register.jsp

  • Attributes (Located in the Application User Attribute section)

  • Attribute Mapping (Located in the Registration Service Details with Application User Attribute Mapping section)

For information about each field, see "Editing or Creating Application Profiles" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

If User Registration is enabled for the application, Mobile and Social redirects to the built-in Mobile and Social User Registration Page. The User can complete the form and register (required if Access Manager is protecting the resource) or skip registration. Mobile and Social then redirects to the application's configured Return URL.

Figure 10-3 The Mobile and Social Built-In User Registration Page

The built-in User Registration Page

10.4.4 Handling the Final Return Response

After User authentication—and optionally after User registration—Mobile and Social redirects back to the application.

Depending on whether the user chose to log in locally or to log in using a Identity Provider, the return response is slightly different.

Local Login Return Response

If the User opted to log in locally, Mobile and Social redirects back to the application's Return URL with the saeToken parameter. The saeToken contains the Mobile and Social generated User Token data, which has been encrypted using the Shared Secret.

Use the RPClient API in the oic_clientsdk to decrypt the saeToken.

For example:

String saeToken = request.getParameter("saeToken");
if (saeToken != null) {
    Map<String, String> saeAttrs = client.getAttrFromSaeToken(saeToken,
                                   ”shared secret value”,”shared secret value”);
    System.out.println("register: saeAttrs :" + saeAttrs);
    String uid = saeAttrs.get ("uid");
    String authType = saeAttrs.get ("authType");
    String oicUserToken = saeAttrs.get ("oicLocalLoginUserToken ");
}

The following block shows the saeToken response attributes:

{uid=weblogic, authType=local,
oicLocalLoginUserToken=eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImJhc2VfZG9tYW
luIn0.eyJleHAiOjEzMzkwODkzMzAxMTgsImF1ZCI6InJlc3Rfc2VydmVyIiwiaXNzIjoiSW50ZXJuZXR
JZGVudGl0eUF1dGhlbnRpY2F0aW9uIiwicHJuIjoid2VibG9naWMiLCJqdGkiOiIyZTVhZmJhZS03ZTQz
LTQwYmMtODIwZS1mODVhN2MyODE2ZWUiLCJvcmFjbGUub2ljLnRva2VuLnR5cGUiOiJVU0VSVE9LRU4iL
CJpYXQiOjEzMzkwODU3MzAxMTgsIm9yYWNsZS5vaWMudG9rZW4udXNlcl9kbiI6InVpZD13ZWJsb2dpYy
xvdT1wZW9wbGUsb3U9bXlyZWFsbSxkYz1iYXNlX2RvbWFpbiJ9.UIZuur_e_uWyFzoig
_mBolPXKIz5BnmmszmB65zsAVNISQ9dui0PRd6F85N-0ZBPKQMf8Xnch0c_mjIt6eXwUD6YD_
Wo0f44svmzM43X74Q2VkMgkH2xM1-3lZEMQb03zZ55CrR5UXpsDKvF54bSa6-jbg2ODZAb2ralEqKiVd0}

See Section 10.4.4.1, "Secured Attribute Exchange (SAE) Token Response Attributes," for information about response attributes.

Identity Provider Login Return Response

If the User opted to log in using an Identity Provider, Mobile and Social redirects back to the application's Return URL (using HTTP POST). The response includes the saeToken parameter, which contains the Mobile and Social generated relying-party User Token data that has been encrypted using the Shared Secret, and the User profile data returned by the Identity Provider.

Use the RPClient API in the oic_clientsdk to decrypt the saeToken.

For example:

String saeToken = request.getParameter("saeToken");
if (saeToken != null) {
    Map<String, String> saeAttrs = client.getAttrFromSaeToken(saeToken,
                                   ”shared secret value”,”shared secret value”);
    System.out.println("register: saeAttrs :" + saeAttrs);
    String uid = saeAttrs.get ("uid");
    String authType = saeAttrs.get ("oicInternetIdentityProvider ");
    String oicUserToken = saeAttrs.get ("internet_identity_user_token");
}

The following block shows the saeToken response attributes:

{uid=example@gmail.com, mail=, timezone=, postaladdress=US, 
internet_identity_user_token=eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImJhc2dn
VfZG9tYWluIn0.eyJleHAiOjEzMzkwODk4OTM4NjQsIm9yYWNsZS5vaWMudG9rZW4ucnAuaWRwX3VyaSI
6Imh0dHBzOi8vd3d3Lmdvb2dsZS5jb20vYWNjb3VudHMvbzgvaWQiLCJvcmFjbGUub2ljLnRva2VuLnJw
LnVzZXJfaWRfdXJpIjoibWFpbHRvOm9pY3VzZXIxMDFAZ21haWwuY29tIiwiYXVkIjoicmVzdF9zZXJ2Z
XIiLCJpc3MiJJbnRlcm5ldElkZW50aXR5QXV0aGVudGljYXRpb24iLCJwcm4iOiJtYWlsdG86b2ljdXNl
cjEwMUBnbWFpbC5jb20iLCJqdGkiOiI0ZTQxNzhkYy1hOWRhLTQxODMtODVkMi1hNDM0MDM5YmZhNzUiL
CJvcmFjbGUub2ljLnRva2VuLnR5cGUiOiJVU0VSVE9LRU4iLCJpYXQiOjEzMzkwODYyOTM4NjQsIm9yYW
NsZS5vaWMudG9rZW4udXNlcl9kbiI6Im1haWx0bzpvaWN1c2VyMTAxQGdtYWlsLmNvbSBodHRwczovL3d
3dy5nb29nbGUuY29tL2FjY291bnRzL284L2lkIn0.K4d_gewCE6N61Ng8DsB31BIEEG1S1wMHWpt5CC8u
yfdMgtpEjzs77yFYzNz5vS6x6lsa8fH2FrSgOlxoyoiOnRF8UfJgCzk3VJIDNoDd_2BsYrBQVLGQzWTbs
avO5x09macq6rmOOT1Jbg9napfol8plqgTHPZgm3CH7Rt7jmxA, preferredlanguage=en-US,
lastname=doe, commonname=johndoe, oicInternetIdentityProvider=Google, password=}

See Section 10.4.4.1, "Secured Attribute Exchange (SAE) Token Response Attributes," for information about response attributes.

10.4.4.1 Secured Attribute Exchange (SAE) Token Response Attributes

The following table describes the saeToken response attributes. These attributes can be used in your code as needed.

Table 10-2 Secured Attribute Exchange (SAE) Token Response Attributes

Attribute Description

uid

The User ID of the User who completed the local login on the Mobile and Social hosted login page.

authType

The type of login that the User selected. For example, authType=local.

oicInternetIdentityProvider

The Identity Provider the User selected. For example, oicInternetIdentityProvider=Google.

oicLocalLoginUserToken

The Mobile and Social generated User token for Users who login locally. You can use this User token in your application to access User profile and other REST services in Mobile and Social.

internet_identity_user_token

The Mobile and Social generated User token for Users who login with an Identity Provider. You can use this User token in your application to access User profile and other REST services in Mobile and Social.


10.5 Integrating With an Access Manager Protected Web Application

You do not have to write code to integrate Internet Identity Services with web applications that are integrated with Access Manager. To complete this integration, use the Mobile and Social and the Access Manager system administration consoles. For instructions, see "Configuring Internet Identity Services" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

10.6 Integrating Internet Identity Services With a Mobile Application

Internet Identity Service provides a mobile-friendly login page if you use a mobile browser to view the login page hosted on the Mobile and Social server. Mobile and Social auto-detects the mobile device and displays the appropriate page. Further configuration is not required.

If you integrate the Internet Identity Services login page in a native mobile app, you can use either the hosted login page or a custom login page that is installed on the device. The code running on the mobile device does not need to know which Identity providers are enabled on the Mobile and Social server. You can add and remove Identity providers on the server without having to update the code that runs on the mobile device.

10.6.1 Defining the Mobile Application on the Mobile and Social Server

Use the Mobile and Social system administration console to define an application profile for the mobile application in Mobile and Social. See "Editing or Creating Application Profiles" Oracle Fusion Middleware Administrator's Guide for Oracle Access Management for help completing this task.

Following is a brief description of some of the items that you need to configure on the Mobile and Social server:

  • Application Name - Provide the name of the application.

  • Mobile Application Return URL - Provide the mobile application's return URL. Mobile and Social uses this URL to send back authentication responses.

  • Shared Secret - Provide the security secret that the mobile application and the Mobile and Social server share to facilitate secure communication.

  • Required Identity Providers - Choose the Identity Providers that the end-user can pick from to authenticate to the application.

  • User Attribute Mappings - Map the user profile attributes that the Identity Provider returns to the user profile attributes that are local to the application.