From d2a76e127a707621e672caeb955d4d14dd9d8ddf Mon Sep 17 00:00:00 2001 From: Pat Losoponkul Date: Fri, 3 May 2024 16:30:07 +0700 Subject: [PATCH] docs: iam oas improvement --- .../identus/agent/server/http/DocModels.scala | 4 +- .../event/controller/EventEndpoints.scala | 6 +-- .../iam/entity/http/EntityEndpoints.scala | 40 +++++++++++++------ 3 files changed, 34 insertions(+), 16 deletions(-) diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/agent/server/http/DocModels.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/agent/server/http/DocModels.scala index 2c1ef2e852..fa72fabd34 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/agent/server/http/DocModels.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/agent/server/http/DocModels.scala @@ -3,6 +3,7 @@ package org.hyperledger.identus.agent.server.http import org.hyperledger.identus.castor.controller.{DIDEndpoints, DIDRegistrarEndpoints} import org.hyperledger.identus.connect.controller.ConnectionEndpoints import org.hyperledger.identus.event.controller.EventEndpoints +import org.hyperledger.identus.iam.entity.http.EntityEndpoints import org.hyperledger.identus.iam.wallet.http.WalletManagementEndpoints import org.hyperledger.identus.issue.controller.IssueEndpoints import org.hyperledger.identus.pollux.credentialdefinition.CredentialDefinitionRegistryEndpoints @@ -117,7 +118,8 @@ object DocModels { DIDRegistrarEndpoints.tag, WalletManagementEndpoints.tag, SystemEndpoints.tag, - EventEndpoints.tag + EventEndpoints.tag, + EntityEndpoints.tag ) ) diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/event/controller/EventEndpoints.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/event/controller/EventEndpoints.scala index a7a0168907..c2d961bde9 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/event/controller/EventEndpoints.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/event/controller/EventEndpoints.scala @@ -22,13 +22,13 @@ object EventEndpoints { private val tagName = "Events" private val tagDescription = - s""" - |The __${tagName}__ endpoints enable users to manage event-related resources, such as webhook notifications. + s"""The __${tagName}__ endpoints enable users to manage event-related resources, such as webhook notifications. |These notifications are specifically designed to inform about events occurring within the wallet, including but not limited to: | |- DID publication notifications - |- Issuance protocol state change notifications |- DIDComm connection notifications + |- Issuance protocol notifications + |- Presentation protocol notifications | |For more detailed information regarding event notifications, please refer to this [documentation](https://docs.atalaprism.io/tutorials/webhooks/webhook). |""".stripMargin diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/iam/entity/http/EntityEndpoints.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/iam/entity/http/EntityEndpoints.scala index d8e5014d3d..fd862a2920 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/iam/entity/http/EntityEndpoints.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/iam/entity/http/EntityEndpoints.scala @@ -8,6 +8,7 @@ import org.hyperledger.identus.iam.authentication.admin.AdminApiKeySecurityLogic import org.hyperledger.identus.iam.authentication.oidc.JwtCredentials import org.hyperledger.identus.iam.authentication.oidc.JwtSecurityLogic.jwtAuthHeader import org.hyperledger.identus.iam.entity.http.model.* +import sttp.apispec.Tag import sttp.model.StatusCode import sttp.tapir.json.zio.jsonBody import sttp.tapir.{Endpoint, EndpointInput, endpoint, extractFromRequest, path, query, statusCode, stringToPath} @@ -16,6 +17,24 @@ import java.util.UUID object EntityEndpoints { + private val tagName = "Identity and Access Management" + private val tagDescription = + s""" + |The __${tagName}__ endpoints allow [agent administrators](https://docs.atalaprism.io/docs/concepts/glossary#administrator) + |to manage identity and access management for the agent's tenants. + |It provides basic built-in IAM capabilities as an alternative to more feature rich external IAM solutions. + | + |Entities are resources that represent individual tenants and + |wallets act as containers for Self-Sovereign Identity (SSI) resources within the agent. + |The administrator can grant tenant access to specific wallets by associating the wallet ID with the Entity. + |Additionally, the administrator can create API keys for entities and provide them to the tenants out-of-band. + |These API keys can then be used for authorization to access specific wallets. + | + |For more detailed information related to the agent IAM and its usage, please refer to this [documentation](https://docs.atalaprism.io/docs/atala-prism/prism-cloud-agent/authentication). + |""".stripMargin + + val tag = Tag(tagName, Some(tagDescription)) + val createEntityEndpoint: Endpoint[ (AdminApiKeyCredentials, JwtCredentials), (RequestContext, CreateEntityRequest), @@ -48,7 +67,7 @@ object EntityEndpoints { .description( "Create the new entity record. The entity record is a representation of the account in the system." ) - .tag("Identity and Access Management") + .tag(tagName) val updateEntityNameEndpoint: Endpoint[ (AdminApiKeyCredentials, JwtCredentials), @@ -84,7 +103,7 @@ object EntityEndpoints { .description( "Update the entity record name by `id`" ) - .tag("Identity and Access Management") + .tag(tagName) val updateEntityWalletIdEndpoint: Endpoint[ (AdminApiKeyCredentials, JwtCredentials), @@ -120,7 +139,7 @@ object EntityEndpoints { .description( "Update the entity record `walletId` field by `id`" ) - .tag("Identity and Access Management") + .tag(tagName) val getEntityByIdEndpoint: Endpoint[ (AdminApiKeyCredentials, JwtCredentials), @@ -145,15 +164,12 @@ object EntityEndpoints { .description( "Get the entity by the unique identifier" ) - .tag("Identity and Access Management") + .tag(tagName) private val paginationInput: EndpointInput[PaginationInput] = EndpointInput.derived[PaginationInput] val getEntitiesEndpoint: Endpoint[ (AdminApiKeyCredentials, JwtCredentials), - ( - RequestContext, - PaginationInput - ), + (RequestContext,PaginationInput), ErrorResponse, EntityResponsePage, Any @@ -171,7 +187,7 @@ object EntityEndpoints { .description( "Get all entities with the pagination by `offset` and `limit` parameters " ) - .tag("Identity and Access Management") + .tag(tagName) val deleteEntityByIdEndpoint: Endpoint[ (AdminApiKeyCredentials, JwtCredentials), @@ -198,7 +214,7 @@ object EntityEndpoints { .description( "Delete the entity by the unique identifier" ) - .tag("Identity and Access Management") + .tag(tagName) val addEntityApiKeyAuthenticationEndpoint: Endpoint[ (AdminApiKeyCredentials, JwtCredentials), @@ -229,7 +245,7 @@ object EntityEndpoints { .description( "Register the `apikey` for the entity." ) - .tag("Identity and Access Management") + .tag(tagName) val deleteEntityApiKeyAuthenticationEndpoint: Endpoint[ (AdminApiKeyCredentials, JwtCredentials), @@ -260,5 +276,5 @@ object EntityEndpoints { .description( "Unregister the `apikey` for the entity." ) - .tag("Identity and Access Management") + .tag(tagName) }