Documentation

You are viewing the documentation for the 2.8.x release series. The latest stable release series is 3.0.x.

§OpenID Support in Play

OpenID is a protocol for users to access several services with a single account. As a web developer, you can use OpenID to offer users a way to log in using an account they already have, such as their Google account. In the enterprise, you may be able to use OpenID to connect to a company’s SSO server.

§The OpenID flow in a nutshell

  1. The user gives you his OpenID (a URL).
  2. Your server inspects the content behind the URL to produce a URL where you need to redirect the user.
  3. The user confirms the authorization on his OpenID provider, and gets redirected back to your server.
  4. Your server receives information from that redirect, and checks with the provider that the information is correct.

Step 1 may be omitted if all your users are using the same OpenID provider (for example if you decide to rely completely on Google accounts).

§Usage

To use OpenID, first add openId to your build.sbt file:

libraryDependencies ++= Seq(
  openId
)

Now any controller or component that wants to use OpenID will have to declare a dependency on the OpenIdClient.

§OpenID in Play

The OpenID API has two important functions:

§Example

conf/routes:

GET     /openID/login               controllers.OpenIDController.login()
POST    /openID/login               controllers.OpenIDController.loginPost(request: Request)
GET     /openID/callback            controllers.OpenIDController.openIDCallback(request: Request)

Controller:

package controllers;

import java.util.*;
import java.util.concurrent.CompletionStage;
import javax.inject.Inject;
import play.data.*;
import play.libs.openid.*;
import play.mvc.*;
import play.twirl.api.Html;

public class OpenIDController extends Controller {

  @Inject OpenIdClient openIdClient;

  @Inject FormFactory formFactory;

  public Result login() {
    return ok(views.html.login.render(""));
  }

  public CompletionStage<Result> loginPost(Http.Request request) {

    // Form data
    DynamicForm requestData = formFactory.form().bindFromRequest(request);
    String openID = requestData.get("openID");

    CompletionStage<String> redirectUrlPromise =
        openIdClient.redirectURL(
            openID, routes.OpenIDController.openIDCallback().absoluteURL(request));

    return redirectUrlPromise
        .thenApply(Controller::redirect)
        .exceptionally(throwable -> badRequest(views.html.login.render(throwable.getMessage())));
  }

  public CompletionStage<Result> openIDCallback(Http.Request request) {

    CompletionStage<UserInfo> userInfoPromise = openIdClient.verifiedId(request);

    CompletionStage<Result> resultPromise =
        userInfoPromise
            .thenApply(userInfo -> ok(userInfo.id() + "\n" + userInfo.attributes()))
            .exceptionally(
                throwable -> badRequest(views.html.login.render(throwable.getMessage())));

    return resultPromise;
  }

  public static class views {
    public static class html {
      public static class login {
        public static Html render(String msg) {
          return javaguide.ws.html.login.render(msg);
        }
      }
    }
  }
}

§Extended Attributes

The OpenID of a user gives you his identity. The protocol also supports getting extended attributes such as the e-mail address, the first name, or the last name.

You may request optional attributes and/or required attributes from the OpenID server. Asking for required attributes means the user cannot login to your service if he doesn’t provide them.

Extended attributes are requested in the redirect URL:

Map<String, String> attributes = new HashMap<>();
attributes.put("email", "http://schema.openid.net/contact/email");

CompletionStage<String> redirectUrlPromise =
    openIdClient.redirectURL(
        openID, routes.OpenIDController.openIDCallback().absoluteURL(request), attributes);

Attributes will then be available in the UserInfo provided by the OpenID server.

Next: Accessing resources protected by OAuth


Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request. Have questions or advice to share? Go to our community forums to start a conversation with the community.