topoos.DigitalIdentity.Net 7.0.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.

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.

Uso

Llamadas HTTP

El SDK dispone de varias clases RestManager, una para cada bloque de operaciones del API, siendo su uso muy similar entre ellas. A continuación se muestra un ejemplo de uso:

string serverUrl = "https://exampledomain.com";
string adminToken = "<admin_token>";
GatewayTokenInfo gatewayToken = new GatewayTokenInfo() { Name = "Authorization", Value = "Bearer <token>" };
/*
 * Instanciamos ClientsRestManager:
 * - serverUrl: url del API Digital Identity.
 * - adminToken: token necesario para ejecutar las operaciones de client.
 * - gatewayToken: configuración del token que nos da el acceso al API (ver documentación de Gateway de topoos).
 */ 
ClientsRestManager manager = new ClientsRestManager(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.