Portunus - the god of keys - a small and simple single sign-on service, that issues and verifies access tokens.
Uses .Net Core 2.1.
For internal use only. Assumes that network is secure. Assumes it is being called from a trusted source.
Configuration is done via appsettings.json file.
The main section of configuration is SSOSettings - it configures applications that you can log into via SSO. Example:
{
"SSOSettings": {
"Apps": [
{ },
{ },
{ }
]
}
}
Each app that needs SSO has to provide following settings:
- app name - serves as a key in dictionary of apps;
- address template of a page that knows how to authenticate user by provided token.
{0}
will be replaced with token string; - expiration time in seconds;
- public and private RSA keys in PEM format;
Example:
{
"AppName": "alpha",
"AuthenticationUrlTemplate": "http://localhost:5001/SSO/Login/{0}",
"ExpireInSeconds": 60,
"TokenProviderSettings": {
"PrivateKey": "RSA private key in PEM format",
"PublicKey": "RSA public key in PEM format"
}
}
App Alpha wants to sign users into App Beta without additional login/password input.
- App Alpha requests a token from Portunus service specifing App Beta as a target.
- Protunus returns address of a page on App Beta that knows how to authenticate user via Portunus.
- App Alpha redirects user to received address.
- App Beta processes a request and asks Portunus to verify a token.
- Portunus performs verification and responds with payload or 401 Unauthorized.
- App Beta processes response from Protunus and authenticates/rejects user.
Portunus exposes two main endpoints - 'issue' and 'verify', plus additional 'healthcheck' endpoint, that simply returns 200 OK.
Issues new access token for specified app with provided payload.
-
URL
api/:app/issue
-
Method
POST
-
URL Params
Required:
app=[string]
-
Data Params
Required:
[object]
-
Success Response
Returns url with generated token from corresponding app's configuration.
- Code: 200 OK
Content:http://localhost:5001/SSO/Login/{token}
- Code: 200 OK
-
Error Response
- Code: 404 NOT FOUND
Reason: Requested app is not in the configuration file
OR
- Code: 400 BAD REQUEST
Reason: Request parameter is invalid
OR
- Code: 500 INTERNAL SERVER ERROR
Reason: Unexpected exception occured
- Code: 404 NOT FOUND
Verifies that access token for specified app is valid.
-
URL
api/:app/verify/:token
-
Method
GET
-
URL Params
Required:
app=[string]
token=[string]
-
Success Response
Returns payload from the token.
- Code: 200 OK
Content:[object]
- Code: 200 OK
-
Error Response
- Code: 401 UNAUTHORIZED
Reason: Token is invalid e.g. expired, was tampered with
OR
- Code: 404 NOT FOUND
Reason: Requested app is not in the configuration file
OR
- Code: 400 BAD REQUEST
Reason: Request parameter is invalid
OR
- Code: 500 INTERNAL SERVER ERROR
Reason: Unexpected exception occured
- Code: 401 UNAUTHORIZED
Returns 200 OK.
-
URL
api/healthcheck
-
Method
GET
-
Success Response
- Code: 200 OK
-
Error Response
- Code: 500 INTERNAL SERVER ERROR
Reason: Unexpected exception occured
- Code: 500 INTERNAL SERVER ERROR
This project is licensed under the MIT License - see the LICENSE file for details