HTTP-based custom authentication

Overview

passport.authenticate('mobilefirst-strategy', {
    session : false
}

To implement custom identity provider, you must expose the following two HTTP endpoints:

• /startAuthorization endpoint. The headers that it receives are those which the client sends to the IBM MobileFirst Platform Foundation and which the server then adds to the request body. For example, the Node.js sample on this page gets the headers by using the following code:

  function(req, res) {
      var returnedJSON = startAuthorization(req.body.headers);
      res.json(returnedJSON);
  }

• /handleChallengeAnswer endpoint. The headers that it receives are those which are received at the /startAuthorization endpoint, with the addition of an answer to a challenge and a state ID. This HTTP endpoint checks the challenge and returns success, challenge, or failure.

The custom identity provider may store some state related to the authentication dialog. An example use case is multi-step authentication, where the custom identity provider needs to store the result of the first authentication step when proceeding to the next step. In this case, the dialog between IBM MobileFirst Platform Foundation authorization server and the custom identity provider becomes stateful. The custom identity provider assigns a state ID, which is sent in the response. The IBM MobileFirst Platform Foundation authorization server passes the state ID in subsequent requests that belong to the client authentication process.

Headers are sent in the body because it is the header from the client request. Sending headers from the client in the body from authorization server to the custom identity provider will prevent conflicts in header names. In case you need to save state between calls to startAuthorization and handleChallengeAnswer, use the optional stateId property in the challenge answer. The custom identity provider and the protected resource may be implemented on the same server or on different servers.

The realm is always in the URL path, just before the endpoint API, as shown in the following examples:

• http://myhost:myport/custom_realm/startAuthorization
• http://myhost:myport/custom_realm/handleChallengeAnswer

Both HTTP endpoints can return three types of JSON response:

• challenge

  { 
  status: "challenge", challenge: 
      { your custom JSON challenge }, 
      stateId : custom state id //state id is optional 
  }

• success

  {
   status: "success", userIdentity: 
      {userName: userName, displayName: displayName, attributes: { your optional custom JSON attributes } }
  }

• failure

  { status: "failure" } 

Samples

The following sample code demonstrates how to implement the startAuthorization and handleChallengeAnswer endpoints in Node.js.

// Call the protected_nodejs_resource
    app.get('/protected_nodejs_resource',
      passport.authenticate('mobilefirst-strategy', {session : false, scope: "customAuthRealm_1 customAuthRealm_2" }), function(req, res) {
       res.status(200).send("Hello capella from node.js")); 
    });

//Implement custom authentication for customAuthRealm_1
    app.post('/customAuthRealm_1/startAuthorization',
        passport.authenticate('mobilefirst-strategy', {
            session : false
        }),
        function(req, res) {
            var returnedJSON = startAuthorization(req.body.headers);
            res.json(returnedJSON);
    });

    app.post('/customAuthRealm_1/handleChallengeAnswer',
            passport.authenticate('mobilefirst-strategy', {
                session : false
            }),     function(req, res) {
            var returnedJSON = handleChallengeAnswer(req.body.headers, req.body.stateId, req.body.challengeAnswer);
            res.json(returnedJSON);
    });


    var startAuthorization = function(headers) {
        return { 
            status: "challenge",
                challenge: {
                    message: "missing_credentials"
                }, 
            stateId : "my_custom_state_id"
        };  
    };


    var handleChallengeAnswer = function(headers, stateId, challengeAnswer) {
        if (challengeAnswer && users[challengeAnswer.userName] && challengeAnswer.password === users[challengeAnswer.userName].password) {
            return {
                status: "success",
                userIdentity: {
                    userName: challengeAnswer.userName,
                    displayName: users[challengeAnswer.userName].displayName,
                    attributes : {"customAttr1":"customValue1", "customAttr2":"customValue2"}

                }
            };
        } else {
            return {
                status: "failure"
            }
        }
    };

The following JAX-RS sample is implemented as a Java REST adapter. The startAuthorization and handleChallengeAnswer endpoints have been implemented in Java.

// Call the protected_java_resource
@GET
@Path("/protected_java_resource")
@Produces("application/json")
@OAuthSecurity (scope="customAuthRealm_1 customAuthRealm_2")
public JSONObject helloCapella(){
    JSONObject hello = new JSONObject();
    hello.put("hello", "Hello Capella");
    return hello;
}



@POST
    @Consumes ("application/json")
    @Path("/customAuthRealm_1/startAuthorization")
    @Produces(MediaType.APPLICATION_JSON)
    public JSONObject startAuthorization(String payload) throws Exception{
        logger.info(payload);
        JSONObject returnJson = (JSONObject) JSON.parse(CHALLENGE_JSON);
        return returnJson;
    }
 
 
   @POST
   @Consumes ("application/json")
   @Path("/customAuthRealm_1/handleChallengeAnswer")
   @Produces(MediaType.APPLICATION_JSON)
    public JSONObject handleChallengeAnswer(String payload) throws Exception{
        JSONObject userStoreJson = (JSONObject) JSON.parse(USER_STORE_JSON);
        JSONObject failedResponseJson = (JSONObject) JSON.parse(FAILURE_JSON);
        
        if(payload == null || payload.isEmpty()) {
            return failedResponseJson;
        }
        JSONObject payloadJson = (JSONObject) JSON.parse(payload);
        JSONObject challengeAnswer = (JSONObject) payloadJson.get("challengeAnswer");
        
        if (challengeAnswer == null ) {
            return failedResponseJson;
        }
        
        String userName = (String) challengeAnswer.get("userName");
        String password = (String) challengeAnswer.get("password");
        
        if (userName == null || userName.isEmpty() || password == null || password.isEmpty()) {
            return failedResponseJson;
        }
        
        if (userStoreJson.containsKey(userName)) {
            JSONObject userInfoJson = (JSONObject) userStoreJson.get(userName);
            String userPassword = (String) userInfoJson.get("password");
            String userDisplayName = (String) userInfoJson.get("displayName");
            
            if (password.equals(userPassword)) {
                JSONObject returnJson = new JSONObject();
                JSONObject userIdentityJson = new JSONObject();
                userIdentityJson.put("userName", userName);
                userIdentityJson.put("displayName", userDisplayName);
                JSONObject customAttributes = new JSONObject();
                customAttributes.put("custom1Key", "custom1Value");
                customAttributes.put("custom2Key", "custom2Value");
                userIdentityJson.put("attributes", customAttributes);
                returnJson.put("status", "success");
                returnJson.put("userIdentity", userIdentityJson);
                return returnJson;
            }            
        }
        
        return failedResponseJson;
    }

For more information

More techniques for implementing custom authentication

• Adapter-based custom authentication. For more information, see Implementing adapter-based authenticators.
• Java-based custom authentication. For more information, see see Implementing Java-based custom authenticators.