Para poder usar estos servicios, el usuario debe haberse autenticado en la plataforma mediante autenticación Oauth2, ya que es necesario utilizar un Token Bearer como Header para cada endpoint.
Los Endpoints comienzan por: '/controlpanel/api/realms'.
Puedes echar un vistazo a todos los endpoints de las APIs disponibles en la interfaz Swagger UI: /controlpanel/swagger-ui.html#RealmManagement
1. GET
1.1. Obtención de Realm
Para obtener información sobre un Realm, puedes utilizar tanto el método GET por Identificador de Realm, o GET sin parámetros para obtener un listado de Realms.
Por identificador de Realm: GET '/controlpanel/api/realms/{identification}'
La respuesta consistirá en un JSON con atributos que representan la información del Realm, tales como identificación, nombre, descripción, roles, usuarios, asociaciones con otros roles,...
Los usuarios administradores podrán obtener la información de cualquier Realm registrado en la plataforma. Si el usuario no es administrador, sólo podrá obtener información de sus propios Realms.
GET all: GET '/controlpanel/api/realms'
Como se ha indicado anteriormente, los administradores obtendrán un listado con todos los Realms disponibles en la plataforma, mientras que el resto de usuarios obtendrán únicamente el listado de sus propios Realms.
1.2. Obtención de los Roles de un Realm
Un usuario puede recuperar una lista de los roles incluídos en un Realm mediante una petición GET a '/controlpanel/mangement/realms/{identification}/roles'
Los usuarios administradores obtendrán la lista de roles de cualquier Realm de plataforma, mientras que el resto de usuarios sólo podrán acceder a esta información para los Realms de los que sean propietarios.
1.3. Obtención de los usuarios registrados en un Realm
También se puede obtener el listado de usuarios incluidos en un Realm:
Buscando por id de usuario: GET '/controlpanel/api/realms/{realmid}/users/{userid}
Se obtendrá la información del usuario:
Los usuarios administradores obtendrán información de qué usuarios se encuentran registrados en cualquier Realm de la plataforma. Si el usuario no es administrador, esta información se verá reducida a los Realms que posea.
All: GET '/controlpanel/api/realms/{realmid}/users'
Ocurre lo mismo que en el caso de acceder a los usuarios registrados en el Realm por ID. Los usuarios administradores consultarán esta información para cualquier Realm, y el resto sólo para los que posean.
2. POST
2.1.Realm creation
Para crear un Realm, es necesario especificar:
El atributo roles es un array de objetos. Cada rol tendrá un nombre y una descripción. Usuarios y asociaciones entre Realms se establecerán después de que el Realm haya sido creado con éxito.
Como información adicional, se puede registrar una clave y el periodo de validez del token (en segundos): si no se introduce valor, se dará uno por defecto, definido en la instalación y despliegue de la plataforma.
Ejemplo: POST '/controlpanel/api/realms'
2.2. Creación de un Rol en un Realm
Si se desea crear roles adicionales en un Realm, que no se especificaron en la creación del mismo, se puede realizar mediante una petición POST a:
POST '/controlpanel/api/realms/{realmid}/roles'
El usuario debe ser el propietario del Realm o disponer de rol Administrador.
2.3. Asociación/Autorización de usuarios a un Realm
Para añadir usuarios a un Realm, debe existir tanto el usuario como un rol dentro del Realm. Si es así, se creará la asociación mediante:
POST '/controlpanel/api/realms/authorization'
Para asociar usuarios a algún Realm, el usuario debe ser el propietario del mismo, o ser un usuario administrador de la plataforma (un usuario con rol administrador).
2.4. Creación de asociaciones entre Realms
Como se ha visto en otras secciones, puedes establecer relaciones y mapeos entre distintos roles de distintos Realms. Para conseguir, esto es necesario declarar el rol del Realm y el rol del Realm a asociar, así como sus respectivos Realms.
Haz una petición POST a '/controlpanel/api/realms/association'
Para establecer asociaciones entre Realms, será necesario que el usuario sea el propietario de ambos o que el usuario sea administrador de la plataforma (un usuario con rol administrador).
3. PUT
3.1. Modificación de un Realm
Por razones de complejidad de back-end, sólo se podrá modificar el nombre, descripción, clave y periodo de validez del token del Realm. Roles, usuarios y asociaciones entre Realms se modificaran mediante sus propios endpoints
Ejemplo: PUT '/controlpanel/api/realms/{id}'
Sólo usuarios propietarios y administradores pueden modificar Realms.
3.2. Modificación de asignaciones de usuarios, Modificación de asociación de realms, Modificación de Roles de Realms.
Para estas operaciones, de momento, es necesario borrar y crear nuevas entidades, ya que la operación PUT no está implementada. Solo los propietarios y los usuarios administradores pueden modificar Realms.
4. DELETE
4.1. Eliminación de Realm
Si deseas eliminar un Realm y sus asociaciones, debes realizar una petición DELETE a '/controlpanel/api/realms/{realmid}'
4.2. Eliminación de roles de Realm
Si quieres eliminar un rol de un Realm, debes invocar mediante una petición DELETE a '/controlpanel/api/realms/{realmid}/roles/{roleName}'
Igual que en el caso anterior, sólo el propietario o un administrador podrá borra un rol de un Realm determinado.
4.3. Eliminación de Usuarios registrados en un Realm
Para eliminar un usuario de un Realm, debes eliminar la autorización de ese usuario al Realm. Esto se consigue realizando una petición DELETE al endpoint '/controlpanel/api/realms/authorization/realm/{realmid}/user/{userid}'
Esta operación sólo puede realizarla el propietario del Realm o un usuario administrador.
4.4. Eliminación de Asociación entre Realms
Para eliminar una asociación entre dos Realms, es necesario especificar el Realm y su rol, así como el Realm asociado y el rol asociado.
DELETE '/controlpanel/api/realms/association/parent-realm/{parentRealmId}/parent-role/{parentRoleName}/child-realm/{childRealmId}/child-role/{childRoleName}
Para eliminar una asociación, el usuario debe ser el propietario de ambos Realms o ser un usuario administrador.