使用Okta的单点登录保护您的Vert.x服务器

“我喜欢编写身份验证和授权代码。” 〜从来没有Java开发人员。 厌倦了一次又一次地建立相同的登录屏幕？尝试使用Okta API进行托管身份验证，授权和多因素身份验证。

Vert.x是Spring生态系统中增长最快的元素之一，保护Vert.x服务器可能是一个挑战。部署Okta可以让您向服务器添加安全的单点登录，同时还可以授予您访问有关用户的大量信息的权限。本教程将指导您站起一个新的Vert.x服务器，并将其与Okta集成以进行安全的用户管理。

三步OAuth流程快速回顾

此示例将使用称为三足流（单点登录的实质）的第三方提供程序OAuth流。在开始编写代码之前，简要回顾一下此过程可能会有所帮助。

问题

我是Web服务器，我想保护我的网站并要求用户登录。但是，编写，维护和管理用户身份是很多工作。

解决方案

让别人来处理它。为此，我（Web服务器），我的用户（可能在Web浏览器上）以及为我处理auth的人（在此示例中为Okta）之间需要一些合作。这三个合作的参与者是三腿OAuth流的三个“腿”。他们经历的过程是三向握手：

用户的浏览器向我的Web服务器请求受保护的资源
我（Web服务器）决定用户首先需要登录。我拒绝处理请求，而是返回302重定向响应，告诉浏览器去访问Okta
浏览器遵从，而是访问Okta，然后用户登录。Okta然后返回其自己的302重定向，告诉浏览器返回并再次访问我…但是这次，携带密码
浏览器再次访问了我，但是这次我看到它带有此秘密代码。现在，我直接打给Okta，将这个密码转换为有关用户的敏感信息，例如姓名，电子邮件地址或电话号码

完成此示例后，上述握手将在幕后发生。 Vert.x提供了一个方便的OAuth库来为您完成整个过程-您所需要做的就是对其进行配置并进行适当的注册。这就是本教程演示的内容。

作为入门指南，本文假定仅基本熟悉Java和一些Java要素，例如Maven。如果您已经在运行Vert.x服务器，请随时快速了解相关内容：您将在“ 配置Vert.x OAuth处理程序”部分中与Okta集成。

完整的代码示例（包括imports和pom.xml）可以在Github上找到。

启动新的Vert.x服务器

要开始工作，请访问Vert.x Starter页面并生成一个新项目。对于本教程，您可以保留所有默认值，并包括Vert.x Web ， OAuth和Vert.x Config依赖项：

单击本地生成，下载和解压缩后，您应该看到以下简单目录结构：

在demo目录中使用mvn compile exec:java运行时，应在端口8080上启动服务器：

在浏览器中访问http://localhost:8080将返回令人放心的hello world响应：

在这一点上，下一步是在继续添加身份验证之前切换到https。但是，为了使本教程简短而集中，将跳过该部分，并且示例将继续使用未加密的http服务器模式。

引入Vert.x配置

Vert.x提供了一个通用的配置库，尽管要比Spring设置更多的工作。本示例将使用一些配置值，因此您可以借此机会将Vert.x Config添加到项目中。如果在创建启动程序项目时指定了Vert.x Config，则该依赖项应该已经存在于pom.xml 。

<dependency><groupId>io.vertx</groupId><artifactId>vertx-config</artifactId><version>${vertx.version}</version>
</dependency>

创建一个名为src/main/application.json的文件，并添加以下内容：

{"clientId": "{okta-client-id}","clientSecret": "{okta-client-secret}","issuer": "https://{yourOktaDomain}/oauth2/default","callbackUrl": "http://localhost:8080/login","port": 8080
}

您将很快更新这些值。现在，在src/main/java/com/example/demo/MainVerticle.java ，将start()方法的内容替换为以下内容，这将加载配置。请注意，完成后，它将调用一个尚不存在的名为startServer()的方法。您将在下一节中添加它。

@Override
public void start() throws Exception {ConfigStoreOptions fileStore = new ConfigStoreOptions().setType("file").setConfig(new JsonObject().put("path", "src/main/application.json"));ConfigRetrieverOptions options = new ConfigRetrieverOptions().addStore(fileStore);ConfigRetriever retriever = ConfigRetriever.create(vertx, options);retriever.getConfig(ar -> {if (ar.failed()) {System.err.println("failed to retrieve config.");} else {config().mergeIn(ar.result());startServer();}});
}

整合Vert.x路由器

通过使用Vert.x路由器，您将能够轻松拦截对敏感端点的呼叫并强制进行预身份验证。为此，您现在将在src/main/java/com/example/demo/MainVerticle.java实现startServer()方法：

void startServer() {Router router = Router.router(vertx);router.route("/private/secret").handler(ctx -> {ctx.response().end("Hi");});vertx.createHttpServer().requestHandler(router::accept).listen(config().getInteger("port"));
}

在上面的示例中，您已经在/private/secret创建了一个新端点，目的是尽快保护/private路径下的每个端点。但首先，需要设置Vert.x OAuth处理程序。

创建Okta帐户并收集凭据

如果您还没有免费的Okta帐户，则可以按照以下说明创建一个帐户并设置您的第一个Okta应用程序。您需要收集四个关键信息：

客户编号-例如： oot9wrjjararhfaa
客户机密-（保持机密！）
发行者–例如： https : //dev-123123.oktapreview.com/oauth2/default…请确保包括/ oauth2 / default路径！
回调网址-如果遵循上述说明，则为http：// localhost：8080 / login 。

现在可以在src/main/application.json文件中使用这些值。

配置Vert.x OAuth处理程序

Vert.x带有一个现成的OAuth管理器，可以与Okta作为身份提供者很好地集成在一起。为了使内容整洁，您将在src/main/java/com/example/demo/MainVerticle.java中创建一个单独的工厂方法，该方法会生成已配置的OAuth处理程序。将以下内容添加到MainVerticle类中，将下面的客户端信息替换为从Okta开发人员仪表板获得的帐户详细信息：

AuthHandler getOAuthHandler(Router router) {OAuth2Auth oauth2 = OAuth2Auth.create(vertx, OAuth2FlowType.AUTH_CODE, new OAuth2ClientOptions().setClientID(config().getString("clientId")).setClientSecret(config().getString("clientSecret")).setSite(config().getString("issuer")).setTokenPath("/v1/token").setAuthorizationPath("/v1/authorize").setUserInfoPath("/v1/userinfo").setUseBasicAuthorizationHeader(false));OAuth2AuthHandler authHandler = OAuth2AuthHandler.create(oauth2, config().getString("callbackUrl"));authHandler.extraParams(new JsonObject("{\"scope\":\"openid profile email\"}"));authHandler.setupCallback(router.route());return authHandler;
}

在上面的示例中，请注意三个请求的范围： openid ， profile和email 。将来的帖子将探讨其他范围和授权级别，但是目前，这三个将提供绝对必要的条件（例如用户名和电子邮件地址）。使用电子邮件地址，您还可以直接查询Okta的API以获取有关用户的其他信息，并执行帐户管理任务。

拦截并授权受保护的端点

现在已经准备好AuthHandler ，它需要在对任何受保护端点的请求处理之前并验证用户身份。通过使用通配符将其注册为/private/下所有路径的顶级处理程序，只需为您将来可能创建的所有处理程序处理一次即可。然后可以保证/private/路径下的任何请求处理程序都将确保，在调用该请求处理程序时，它将仅来自经过正确身份验证的用户。

如下所示更改MainVerticle类的startServer()方法，以生成并注册处理程序：

public void startServer() {Router router = Router.router(vertx);//create and register the auth handler to intercept all//requests below the /private/ URI:AuthHandler authHandler = getOAuthHandler(router);router.route("/private/*").handler(authHandler);router.route("/private/secret").handler(ctx -> {ctx.response().end("Hi");});vertx.createHttpServer().requestHandler(router::accept).listen(config().getString(“port”));
}

这将是重新启动服务器并确保一切正常运行的绝佳时机。通过再次运行mvn compile java:exec并从浏览器中访问http://localhost:8080/private/secret ，您现在应该被自动重定向到Okta的登录页面。登录后，应将您重定向回您的站点，以继续响应原始的/private/secret请求。

从JWT提取用户信息

现在，您的/private/ API的调用者已登录，接下来您需要的是他们的信息。它以JSON Web令牌的形式提供，必须将其提取并解码。 Vert.x OAuth处理程序将其隐藏为名为Principal的字符串化JSON对象的命名成员，该对象本身是上下文用户对象的组成部分。然后使用您选择的JWT库对该编码的令牌进行解码和验证。本示例使用Okta的JWT验证程序库。

access_token和id_token均可用，但是本教程将仅解码id_token 。如果需要，还有一个类似的函数可以对access_token进行解码。为此，请在pom.xml包含Okta JWT lib依赖项：

<dependency><groupId>com.okta.jwt</groupId><artifactId>okta-jwt-verifier</artifactId><version>0.2.0</version>
</dependency>

…并将以下新函数添加到MainVertical类中：

Map<String, Object> getIdClaims(RoutingContext ctx) {try {JwtVerifier jwtVerifier = new JwtHelper().setIssuerUrl(config().getString(“issuer”)).setAudience("api://default").setClientId(config().getString("clientId")).build();Jwt idTokenJwt = jwtVerifier.decodeIdToken(ctx.user().principal().getString("id_token"), null);return idTokenJwt.getClaims();} catch (Exception e) {//do something with the exception...return new HashMap<>();}
}

就是这样！现在，您可以在请求处理程序中访问用户信息。为了演示，可以对/private/secret处理程序进行更新以从JWT检索声明，如下所示：

void startServer() {Router router = Router.router(vertx);AuthHandler authHandler = getOAuthHandler(router);router.route("/private/*").handler(authHandler);router.route("/private/secret").handler(ctx -> {Map claims = getIdClaims(ctx);ctx.response().end("Hi " +claims.get("name") +", the email address we have on file for you is: "+claims.get("email"));});vertx.createHttpServer().requestHandler(router::accept).listen(config().getString(“port”));
}

经过最后的更改，重新启动服务器并再次点击http://localhost:8080/private/secret ，您的浏览器现在应该显示一条消息，其中包含您已通过身份验证的用户信息！