第 5 章 ActiveDocs 和 OAuth
ActiveDocs 允许您从一个位置测试和调用支持 OAuth 的 API。
先决条件
- 您需要设置红帽单点登录实例,并且配置 OpenID Connect 集成。有关如何设置的信息,请参阅 OpenID Connect 集成 文档。
- 另外,您需要熟悉如何设置 ActiveDocs - 请参阅将 ActiveDocs 添加到 3scale 并创建 OpenAPI 规格。
5.1. 3scale 规范中的客户端凭证和资源所有者流示例
第一个示例是在 3scale 规格中使用 OAuth 2.0 客户端凭证流的 API。此 API 接受任何路径,并返回有关请求的信息(路径、请求参数、标头等)。Echo API 只能通过使用有效的访问令牌来访问。API 用户只能在交换其凭据(client_id 和 )来获取访问令牌后将其调用。
client_secret
要使用户能够从 ActiveDocs 调用 API,他们必须请求访问令牌。由于这仅仅是对 OAuth 授权服务器的调用,因此您可以为 OAuth 令牌端点创建 ActiveDocs 规格。这允许从 ActiveDocs 中调用此端点。在本例中,对于客户端凭证流,Swagger JSON 规格类似如下:
{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "OAuth for Echo API",
"description": "OAuth2.0 Client Credentails Flow for authentication of our Echo API.",
"contact": {
"name": "API Support",
"url": "http://www.swagger.io/support",
"email": "support@swagger.io"
}
},
"host": "red-hat-sso-instance.example.com",
"basePath": "/auth/realms/realm-example/protocol/openid-connect",
"schemes": [
"http"
],
"paths": {
"/token": {
"post": {
"description": "This operation returns the access token for the API. You must call this before calling any other endpoints.",
"operationId": "oauth",
"parameters": [
{
"name": "client_id",
"description": "Your client id",
"type": "string",
"in": "query",
"required": true
},
{
"name": "client_secret",
"description": "Your client secret",
"type": "string",
"in": "query",
"required": true
},
{
"name": "grant_type",
"description": "OAuth2 Grant Type",
"type": "string",
"default": "client_credentials",
"required": true,
"in": "query",
"enum": [
"client_credentials",
"authorization_code",
"refresh_token",
"password"
]
}
]
}
}
}
}对于资源所有者 OAuth 流,为用户名和密码以及发布访问令牌所需的其他参数添加参数。对于此客户端凭据流,您将发送 client_id 和 client_secret,这些值可以从已签名用户以及 grant_type 的 3scale 值填充。
然后,在 Echo API 的 ActiveDocs 规格中添加 access_token 参数,而不是 client_id 和 client_secret。
{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "Echo API",
"description": "A simple API that accepts any path and returns information about the request",
"contact": {
"name": "API Support",
"url": "http://www.swagger.io/support",
"email": "support@swagger.io"
}
},
"host": "echo-api.3scale.net",
"basePath": "/v1/words",
"schemes": [
"http"
],
"produces": [
"application/json"
],
"paths": {
"/{word}.json": {
"get": {
"description": "This operation returns information about the request (path, request parameters, headers, etc.),
"operationId": "wordsGet",
"summary": "Returns the path of a given word",
"parameters": [
{
"name": "word",
"description": "The word related to the path",
"type": "string",
"in": "path",
"required": true
},
{
"name": "access_token",
"description": "Your access token",
"type": "string",
"in": "query",
"required": true
}
]
}
}
}
}然后您可以像往常一样在开发人员门户中包含您的 ActiveDocs。在这种情况下,由于您要指定它们首先显示 OAuth 端点的顺序,所以它类似如下:
{% active_docs version: "2.0" services: "oauth" %}
<script type="text/javascript">
$(function () {
window.swaggerUi.load(); // <-- loads first swagger-ui
// do second swagger-ui
var url = "/swagger/spec/echo-api.json";
window.anotherSwaggerUi = new SwaggerUi({
url: url,
dom_id: "another-swagger-ui-container",
supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
onComplete: function(swaggerApi, swaggerUi) {
$('#another-swagger-ui-container pre code').each(function(i, e) {hljs.highlightBlock(e)});
},
onFailure: function(data) {
log("Unable to Load Echo-API-SwaggerUI");
},
docExpansion: "list",
transport: function(httpClient, obj) {
log("[swagger-ui]>>> custom transport.");
return ApiDocsProxy.execute(httpClient, obj);
}
});
window.anotherSwaggerUi.load();
});
</script>