红帽全球峰会第 5 章 ActiveDocs 和 OAuth
ActiveDocs 允许用户从一个位置测试和调用启用了 OAuth 的 API。
先决条件
- 您需要设置 Red Hat Single Sign-On 实例，并配置了 OpenID Connect 集成。有关如何设置它的信息，请参阅 OpenID Connect 集成 文档。
- 另外，您需要熟悉如何设置 ActiveDocs - 请参阅将 ActiveDocs 添加到 3scale 和创建 OpenAPI 规格。
5.1. 3scale 规格中的客户端凭证和资源所有者流示例
复制链接链接已复制到粘贴板!
第一个示例是在 3scale 规格中使用 OAuth 2.0 客户端凭证流的 API。此 API 接受任何路径并返回有关请求的信息（path、请求标头、标头等）。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"
]
}
]
}
}
}
}
{
"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，这可从对签名用户的 3scale 值填充，以及 grant_type。
然后，在 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
}
]
}
}
}
}
{
"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
}
]
}
}
}
}然后您可以在 Developer Portal 中包含 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>
{% 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>
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}