Spring Security 集成 Okta 实战指南

1. 概述

Okta 是一个功能强大的身份管理平台，提供认证、授权、社交登录等能力，广泛用于 Web、移动端和 API 服务。它对 Spring 生态有原生支持，集成起来非常简单直接，堪称“开箱即用”。

本文将带你一步步实现 Spring Security 与 Okta 的集成，并完成一个最小化的开发者账号配置流程。✅

2. 配置 Okta 账号

2.1. 注册开发者账号

首先，前往 Okta 开发者官网 注册一个免费账号。该账号支持最多 1000 个活跃用户，完全满足开发和测试需求。

如果你已有账号，可直接跳过此步。

2.2. 仪表盘概览

登录后进入主仪表盘，可以看到当前组织的用户数、登录次数、失败登录等统计信息。

同时，系统日志也会实时展示关键操作记录：

⚠️ 注意右上角的 Org URL（如 https://dev-example123.okta.com），后续配置 Spring Boot 应用时会用到。

2.3. 创建新应用

在左侧菜单选择 Applications → Create App Integration，创建一个新的应用。

选择应用类型时，注意：

• ✅ Web：适用于传统的服务端渲染或前后端不分离的 Spring Boot 应用
• ❌ Native / Single-Page App / Service：适用于移动端、SPA 或微服务间调用

选择 Web 平台：

2.4. 应用配置

接下来填写应用的基本信息：

• Base URIs：填写你的应用地址，如 http://localhost:8080
• Login redirect URIs：填写登录回调地址，如 http://localhost:8080/authorization-code/callback

同时，务必勾选 Authorization Code 授权类型，这是 Web 应用使用 OAuth2 登录的必要条件。

2.5. 获取客户端凭证

保存后，Okta 会生成一对 Client ID 和 Client Secret，这是你的应用与 Okta 通信的“钥匙”。

请妥善保管，尤其是 Client Secret，一旦丢失只能重新生成。

3. Spring Boot 应用集成

Okta 侧配置完成后，接下来在 Spring Boot 项目中接入。

3.1. Maven 依赖

引入 okta-spring-boot-starter，它封装了 Spring Security 与 Okta 的集成逻辑：

<dependency>
    <groupId>com.okta.spring</groupId>
    <artifactId>okta-spring-boot-starter</artifactId>
    <version>3.0.6</version>
</dependency>

3.2. Gradle 依赖

若使用 Gradle：

compile 'com.okta.spring:okta-spring-boot-starter:1.4.0'

⚠️ 注意版本一致性，避免踩坑。

3.3. 配置文件设置

在 application.properties 中填入 Okta 相关配置：

okta.oauth2.issuer=https://dev-example123.okta.com/oauth2/default
okta.oauth2.client-id=1230oaa4yncmaxaQ90ccJwl4x6
okta.oauth2.client-secret=hjiyblEzgT0ItY91Ywcdzwa78oNhtrYqNklQ5vLzvruT123
okta.oauth2.redirect-uri=/authorization-code/callback

说明：

• issuer：使用默认的授权服务器地址 {orgURL}/oauth2/default
• client-id 和 client-secret：来自上一步 Okta 控制台
• redirect-uri：必须与应用配置中的回调地址一致

你也可以在 Okta 控制台的 API → Authorization Servers 中创建自定义授权服务器：

4. 主页接口开发

创建一个简单的 HomeController 来测试登录流程：

@RestController
public class HomeController {
    @GetMapping("/")
    public String home(@AuthenticationPrincipal OidcUser user) {
        return "Welcome, "+ user.getFullName() + "!";
    }
}

关键点：

• @AuthenticationPrincipal 注解用于注入当前认证用户
• OidcUser 是 Spring Security 提供的 OpenID Connect 用户对象，可获取用户姓名、邮箱等信息

启动应用：

mvn spring-boot:run

访问 http://localhost:8080，会自动跳转到 Okta 的登录页：

登录成功后，返回欢迎页面：

底部的 “Sign up” 链接支持用户自助注册。

5. 用户注册管理

5.1. 自助注册

新用户可通过登录页的 “Sign up” 链接自助注册，填写邮箱、姓名等信息：

5.2. 后台创建用户

管理员也可在 Okta 控制台的 Users → People 中手动创建用户：

5.3. 注册策略配置

在 Users → Registration 中可配置注册策略，例如是否允许自助注册、邮箱域名限制等：

6. 集成 Okta SDK 管理 API

除了认证，我们还可以通过 Okta SDK 在应用内管理用户、应用等资源。

6.1. 创建 API Token

在 Okta 控制台的 API → Tokens 中创建一个管理 Token：

⚠️ Token 仅显示一次，请立即复制保存。

6.2. 添加 SDK 依赖

引入 okta-spring-sdk：

<dependency>
    <groupId>com.okta.spring</groupId>
    <artifactId>okta-spring-sdk</artifactId>
    <version>1.4.0</version>
</dependency>

6.3. 配置 SDK

在 application.properties 中添加：

okta.client.orgUrl=https://dev-example123.okta.com
okta.client.token=00TVXDNx1e2FgvxP4jLlONbPMzrBDLwESSf9hZSvMI123

6.4. 创建 AdminController

注入 Client 对象，即可调用 Okta 管理 API：

@RestController
public class AdminController {
    @Autowired
    public Client client;
}

6.5. 查询用户列表

@GetMapping("/users") 
public UserList getUsers() { 
    return client.listUsers(); 
}

访问 http://localhost:8080/users，返回所有用户信息（已脱敏）：

{
    "dirty": false,
    "propertyDescriptors": {
        "items": {
            "name": "items",
            "type": "com.okta.sdk.resource.user.User"
        }
    },
    "resourceHref": "/api/v1/users",
    "currentPage": {
        "items": [
            {
                "id": "00uanxiv7naevaEL14x6",
                "profile": {
                    "firstName": "Anshul",
                    "lastName": "Bansal",
                    "email": "anshul@bansal.com"
                }
            },
            {
                "id": "00uag6vugXMeBmXky4x6",
                "profile": {
                    "firstName": "Ansh",
                    "lastName": "Bans",
                    "email": "ansh@bans.com"
                }
            }
        ]
    },
    "empty": false
}

6.6. 按条件搜索用户

支持通过 firstName、lastName、email 等字段搜索：

@GetMapping("/user")
public UserList searchUserByEmail(@RequestParam String query) {
    return client.listUsers(query, null, null, null, null);
}

示例：http://localhost:8080/user?query=ansh@bans.com

返回结果：

{
    "resourceHref": "/api/v1/users?q=ansh%40bans.com",
    "currentPage": {
        "items": [
            {
                "id": "00uag6vugXMeBmXky4x6",
                "profile": {
                    "firstName": "Ansh",
                    "lastName": "Bans",
                    "email": "ansh@bans.com"
                }
            }
        ]
    }
}

6.7. 创建新用户

@GetMapping("/createUser")
public User createUser() {
    char[] tempPassword = {'P','a','$','$','w','0','r','d'};
    User user = UserBuilder.instance()
        .setEmail("norman@lewis.com")
        .setFirstName("Norman")
        .setLastName("Lewis")
        .setPassword(tempPassword)
        .setActive(true)
        .buildAndCreate(client);
    return user;
}

调用后返回创建的用户信息，包含重置密码链接等元数据。

✅ 你还可以用 SDK 实现：应用管理、分组管理、角色分配等高级操作。

7. 总结

本文实战演示了如何将 Spring Security 与 Okta 深度集成：

1. ✅ 配置 Okta 开发者账号与应用
2. ✅ Spring Boot 集成 OAuth2 登录
3. ✅ 使用 @AuthenticationPrincipal 获取用户信息
4. ✅ 集成 Okta SDK 实现用户管理

整个流程简单粗暴，适合中大型系统快速接入统一身份认证。所有代码示例已上传至 GitHub：

👉 https://github.com/eugenp/tutorials/tree/master/spring-security-modules/spring-security-okta