topoos.DigitalIdentity.Net 8.0.5

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.

Se distribuye mediante paquete Nuget, el cual se entrega mediante un pipeline programado de continuous delivery.

Instalación

Nuget

Para instalarlo en cualquier proyecto de Visual Studio compatible se utiliza la herramienta de gestión de paquetes Nuget y descargándolo como cualquier otro paquete, siendo el nombre del mismo topoos.DigitalIdentity.Net.

Desarrollo local

Si se desea ampliar el SDK el procedimiento recomendado es el siguiente:

• Descargar el código fuente del SDK del correspondiente repositorio. Opcionalmente también se puede añadir como submódulo de Git.
• Crear un proyecto de demostración, siguiendo el ejemplo del siguiente proyecto, que haga uso de las funcionalidades del SDK.
• Añadir el proyecto del SDK al proyecto de demostración utilizando la opción de Visual Studio de Agregar > Proyecto existente y referenciarlo desde el proyecto principal.
• El proyecto no se copiará sino que se hará un enlace por lo que cualquier cambio que hagamos en el código fuente del proyecto del SDK desde Visual Studio se podrá consolidar en el repositorio rápidamente.

Implementación

Para desarrollar el flujo de integración OAuth se desarrollaron dos extensiones del código del framework .NET utilizado para configurar middlewares:

public static IServiceCollection AddDigitalIdentity(this IServiceCollection services, DigitalIdentityOptions digitalOptions)

public static IApplicationBuilder UseDigitalIdentity(this IApplicationBuilder app)

AddDigitalIdentity hace uso de la funcionalidad de la que ya dispone el framework de .NET para configurar la integración con flujos Oauth 2.0, para la cual se le debe indicar la configuración de esquema de autenticación, cookies, los parámetros Oauth y la clase que actuará como manejadora del flujo. Esta clase, implementada en el SDK en la DigitalIdentityOAuthHandler, es la que implementa todos los detalles de comunicación e intercambio de claves con el API de Digital Identity.

Publicación

El proyecto tiene programado un flujo de continuous delivery que publica automáticamente el paquete en Nuget.org ante cualquier commit etiquetado. No obstante existe una duplicidad de etiquetas ya que por un lado tenemos la etiqueta de Git y por otro lado la etiqueta del propio paquete siendo esta última la que se utiliza para publicar el paquete en Nuget.

Los metadatos de publicación del paquete se encuentran en el fichero src/DotNetDigitalIdentitySDK/DotNetDigitalIdentitySDK.csproj y la forma más sencilla de editarlos es utilizando Visual Studio, abriendo las propiedades del proyecto DotNetDigitalIdentitySDK mediante su menú contextual y accediendo a Propiedades > Paquete.

El procedimiento de publicación de una nueva versión del SDK será el siguiente:

• Actualizamos la versión, siguiendo SEMVER, del paquete Nuget actualizando el fichero DotNetDigitalIdentitySDK.csproj.
• Actualizamos el documento CHANGELOG.md, indicando los cambios realizados.
• Hacemos el commit, mergeamos a la rama correspondiente de acuerdo a git flow y hacemos un tag.
• Podemos consultar el estado del pipeline en el siguiente enlace.

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/3.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.