topoos.DigitalIdentity.Net 7.1.0

topoos.DigitalIdentity.Net

SDK desarrollado en .NET Core 3.1 para el API versión 3.0.0 de Digital Identity de topoos.

El SDK además de implementar las llamadas HTTP y parseo de respuestas dispone de funcionalidad para realizar el flujo Oauth 2.0 contra Digital Identity y facilitar enormemente la integración con el mismo, tal y como veremos más adelante.

Uso

Llamadas HTTP

El SDK dispone de varias clases Manager, una para cada bloque de operaciones del API, siendo su uso muy similar entre ellas. Todos los managers están diseñados para funcionar conectados tanto al servicio DigitalIdentity de topoos como a una instalación on premise del mismo. A continuación se muestra un ejemplo de uso de cada escenario:

Entorno de topoos

GatewayTokenInfo gatewayToken = new GatewayTokenInfo("Bearer <token>");
/*
 * Instanciamos Applications:
 * - gatewayToken: configuración del token que nos da el acceso al API (ver documentación de Gateway de topoos).
 */ 
Applications appsManager = new Applications(gatewayToken);
string clientName = "testClient";
string redirectUrl = "https://exampledomain.com/authorized";
/*
 * Invocamos la operación de crear un cliente.
 *  - clientName: nombre del cliente.
 *  - redirectUri: url de redirección.
 */
DigitalIdentityClient clientResult = await appsManager.Create(clientName, redirectUrl);
// En DigitalIdentityClient tenemos la respuesta parseada.

Entorno on premise

string serverUrl = "https://exampledomain.com";
string adminToken = "<admin_token>";
// Será necesario añadir este token de autorización si el servicio está protegido por un gateway
// GatewayTokenInfo gatewayToken = null;
/*
 * Instanciamos ClientsRestManager:
 * - serverUrl: url del API Digital Identity.
 * - adminToken: token necesario para ejecutar las operaciones de client.
 */ 
Applications appsManager = new Clients(serverUrl, adminToken, /* gatewayToken */);
string clientName = "testClient";
string redirectUrl = "https://exampledomain.com/authorized";
/*
 * Invocamos la operación de crear un cliente.
 *  - clientName: nombre del cliente.
 *  - redirectUri: url de redirección.
 */
DigitalIdentityClient clientResult = await clientManager.Create(clientName, redirectUrl);
// En DigitalIdentityClient tenemos la respuesta parseada.

Integración del flujo Oauth 2.0

El SDK además facilita enormemente integrar el flujo de Oauth 2.0 de forma que una vez configurado, cuando se vaya a acceder a un controlador marcado con la anotación [Authorized], se resolverá automáticamente el flujo Oauth 2.0 si el usuario no está logado, y se le acabará proporcionando al usuario su token de acceso.

Configuración de la integración

En primer lugar se deben configurar los parámetros de conexión con el servicio de Digital Identity y los datos del cliente Oauth. Para ello se recomienda hacer un fichero de configuración JSON. Este fichero debe tener la siguiente forma:

{
  "DigitalIdentityOptions": {
    "BaseUrl": "https://digitalidentity.topoos.com", // url base de la web. Opcional. Valor por defecto: https://digitalidentity.topoos.com
    "ServerUrl": "https://api.topoos.com/digitalidentity/1.0.0", // url base del api. Opcional. Valor por defecto: https://api.topoos.com/digitalidentity/1.0.0
    "AdminToken": "<admin_token>", // clave de administración del servicio. Obligatorio
    "ClientId": "<client_id>", // identificador del cliente Oauth. Obligatorio
    "ClientSecret": "<client_secret>", // clave secreta del cliente Oauth. Obligatorio
    "ApiKey": "<api_key>", // clave API del cliente Oauth. Obligatorio
    "CallbackPath": "/login/authorized", // Endpoint al que se llama una vez logado el usuario. Opcional. Valor por defecto: /login/authorized
    "AuthorizationEndpoint": "/oauth/login", // Endpoint de autorización. Opcional. Valor por defecto: /oauth/login
    "TokenEndpoint": "/oauth/access_token", // Endpoint de intercambio de código de autorización por token de acceso. Opcional. Valor por defecto: /oauth/access_token
    "UserInformationEndpoint": "/who", // Endpoint de consulta de información del usuario/token de acceso. Opcional. Valor por defecto: /who
    "GatewayToken": {
      "Name": "Authorization", // Nombre de la cabecera de autorización que consulta el Gateway encargado de proteger el acceso a las APIs del bus. Opcional. Valor por defecto: Authorization
      "Value": "<gateway_token_value>" // Valor de la cabecera de autorización que consulta el Gateway encargado de proteger el acceso a las APIs del bus. Obligatorio
    }
  }
}

A continuación se debe configurar el middleware de autenticación en la clase Startup.cs, utilizando las extensiones proporcionadas por el SDK a este aspecto. Para ello primero configuramos el middleware en la función ConfigureServices.

public void ConfigureServices(IServiceCollection services) {
  ...
  DigitalIdentityOptions digitalIdentityOptions = new DigitalIdentityOptions();
  Configuration.GetSection("DigitalIdentityOptions").Bind(digitalIdentityOptions);
  services.AddDigitalIdentity(digitalIdentityOptions); 
  ...
}

A continuación se debe añadir el middleware al flujo de procesamiento de las peticiones HTTP, en la función Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
  ...
  app.UseDigitalIdentity();
  ...
}

Una vez configurada la integración, cualquier controlador que se marque con la anotación [Authorized], estará protegido de forma que el usuario sólo podrá acceder a las operaciones del controlador si está logado, y en caso de no estarlo le aparecerá el formulario de login de Digital Identity.

...
[Authorize]
public class PrivateController : BaseController
{
}
...

Por último, se recomienda añadir un controlador de operaciones de Login para poder invocar el login bajo cualquier condición que se desee y para poder ejecutar la operación de logout:

...
public class LoginController : BaseController
{
  public LoginController(ILogger<BaseController> logger, IOptions<ConnectionStrings> connectionStrings, IOptions<KeysSettings> keysSettings, IConfiguration configuration) : base(logger, connectionStrings, keysSettings, configuration) { }

  // GET: Login
  public ActionResult Index(string returnUrl = "/")
  {
    return Challenge(new AuthenticationProperties() { RedirectUri = returnUrl });
  }

  public async Task<ActionResult> Logout()
  {
    await HttpContext.SignOutAsync();
    return RedirectToAction("Index", "Home");
  }
}
...

Consulta de datos de usuario

El SDK dispone de la interfaz IIdentityExtractor que facilita en gran medida la obtención de información del usuario logado. A continuación se incluye un ejemplo en el que se utiliza la mencionada clase en un objeto de tipo ViewComponent.

...
public class UserInfoViewComponent : ViewComponent
{
  private readonly ILogger logger;
  private readonly IIdentityExtractor identityExtractor;

  public UserInfoViewComponent(ILogger<UserInfoViewComponent> logger, IIdentityExtractor identityExtractor)
  {
    this.logger = logger;
    this.identityExtractor = identityExtractor;
  }

  public IViewComponentResult Invoke()
  {
    UserIdentity userIdentity = identityExtractor.GetUserIdentity(UserClaimsPrincipal.Claims);
    UserView user = new UserView()
    {
      Name = userIdentity.Name,
      Email = userIdentity.Email,
      Status = userIdentity.Status,
    };
    return View("UserInfo", user);
  }
}
...

Contributing & License

Consultar www.solusoft.es 2020 todos los derechos reservados.