This module contains types that outline a system for identification and authorization.
This module may be a bit ambitious.... It defines an entire Accounts API, which is a bit specific (and also
implemented in https://github.com/wymp/ts-auth-gateway/ as a sort of POC).
Identification is the process of determining who an entity claims to be.
Authentication is the process of verifying that the entity actually is who they say they are (using a secret or
password).
Authorization is the process of verifying that the entity is allowed to do what they are trying to do.
In the auth paradigm defined by this module, we have clients and users. We identify clients by clientId and
users by userId. We authenticate clients using a secret key and users using a password and (optional) 2fa code. We
authorize clients and users using client roles and user roles. And (optionally) we further authorize clients using
OAuth scopes granted by users.
In this system, a request may be associated with just a client (a computer-to-computer interaction) or a client and
a user (a user-to-computer interaction). In either case, the client may be authenticated or not. Generally speaking,
requests coming from front-end clients (e.g., your website) will NOT be authenticated, since you cannot safely
expose your client secret to the front-end. Requests coming from back-end clients (e.g., your internal services)
should be authenticated so that you can prove they are genuine.
There is an additional layer in all of this which is not considered important to the authn/z system, and that is
"organizations". An organization is an arbitrary group of users. An organization is not considered an actor, so it
is not part of the primary authn/z system, but it is considered a first-class member of the "accounts" system.
There is a third-party website, https://other-domain.com/app, that wants to use your service. Here's how that would
work:
An admin from other-domain goes to https://my-domain.com/signup and creates an account. That account-creation
request is identified by YOUR clientId, 12345; it is NOT authenticated (because it's a front-end request), and
there is no user associated with it because they haven't been created yet.
The creation is successful and a session is returned with user data. The admin goes and does some other things on
your website, including creating a new client, id abcde. This creation request is identified by YOUR client, 12345,
(because this is still your website); it's still unauthenticated because it's a front-end request, but now it's
associated with the admin's authenticated user.
Now the admin has their own client id, abcde. They get their website up and running and make a request to your
general stats API, https://apis.my-domain.com/stats. This request is identified by THEIR client, abcde, and is
NOT authenticated (because it's a front-end request).
Meanwhile, they're server is making AUTHENTICATED requests to a private endpoint on your stats API. These requests
are identified by THEIR client, abcde, and are authenticated using their client secret; however, they are not
associated with a user.
Finally, they take a user through an OAuth flow and obtain an OAuth token for the user from your site. They use
that token to make requests to your user API, https://apis.my-domain.com/users, on behalf of the user. These
requests are identified by THEIR client, abcde; they are NOT authenticated (front-end request); but they are
now associated with the user, and they contain OAuth scopes that you can use to authorize the request.
The above example attempts to demonstrate the ReqInfo data that would be present in each of these cases. However,
how you facilitate the transmission of this data is up to you. https://github.com/wymp/ts-auth-gateway/ provides
a full, working example of a system that does this.
Auth types for the Wymp ecosystem.
This module contains types that outline a system for identification and authorization.
This module may be a bit ambitious.... It defines an entire Accounts API, which is a bit specific (and also implemented in https://github.com/wymp/ts-auth-gateway/ as a sort of POC).
Concept
Identification, Authentication and Authorization
In the auth paradigm defined by this module, we have clients and users. We identify clients by clientId and users by userId. We authenticate clients using a secret key and users using a password and (optional) 2fa code. We authorize clients and users using client roles and user roles. And (optionally) we further authorize clients using OAuth scopes granted by users.
Auth Data
In this system, a request may be associated with just a client (a computer-to-computer interaction) or a client and a user (a user-to-computer interaction). In either case, the client may be authenticated or not. Generally speaking, requests coming from front-end clients (e.g., your website) will NOT be authenticated, since you cannot safely expose your client secret to the front-end. Requests coming from back-end clients (e.g., your internal services) should be authenticated so that you can prove they are genuine.
There is an additional layer in all of this which is not considered important to the authn/z system, and that is "organizations". An organization is an arbitrary group of users. An organization is not considered an actor, so it is not part of the primary authn/z system, but it is considered a first-class member of the "accounts" system.
Full Usage Example
As an example, let's say you run a service at https://my-domain.com that provides an API that other websites want to use. Your API provides general data via endpoints at https://apis.my-domain.com/stats and user-specific data via endpoints at https://apis.my-domain.com/users.
There is a third-party website, https://other-domain.com/app, that wants to use your service. Here's how that would work:
The above example attempts to demonstrate the
ReqInfodata that would be present in each of these cases. However, how you facilitate the transmission of this data is up to you. https://github.com/wymp/ts-auth-gateway/ provides a full, working example of a system that does this.