identity-api is an OAuth service that supports the following grant types:
identity-api is a Go service. To build it, you can either use make build to build a Go binary or make up to both build and start the service.
The up Makefile target will auto-generate a private key and mount it in the container for testing purposes. Note that this is not recommended for actual production use, and is merely a handy feature to allow developers to test.
To perform a token exchange, seed your database with a trusted issuer. Then, try running the following:
$ read -s -p 'Enter your token: ' AUTH_TOKEN && echo
$ curl -XPOST -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token=$AUTH_TOKEN&subject_token_type=urn:ietf:params:oauth:token-type:jwt" http://localhost:8000/token | jq
This sends an RFC 8693 token exchange request to identity-api, which then will validate the given subject token against the configured subject token issuers. If the token is valid, you will receive a response like so (access token truncated for brevity):
{
"access_token": "eyJ..VwM",
"expires_in": 100,
"token_type": "urn:ietf:params:oauth:token-type:jwt"
}
To examine the payload of the access token JWT itself, you can use jq to decode the payload:
$ echo "$ACCESS_TOKEN" | jq '.access_token | split(".") | .[1] | @base64d | fromjson'
{
"aud": [],
"client_id": "my-client",
"exp": 1670354213,
"iat": 1670354113,
"iss": "https://iam.infratographer.com/",
"jti": "e36322d3-414c-4da2-91a8-f19a6e9fb1d3",
"scp": [],
"sub": "my-user-id"
}
The JSON Web Key Set (JWKS) used for signing identity-api JWTs is available at /jwks.json.
identity-api requires a configuration file to run. An example can be found at identity-api.example.yaml.
Private keys must be explicitly configured with a JWT signing algorithm, such as HS256 or RS256. Symmetric keys are loaded from key files as raw bytes. All asymmetric (i.e., RSA) signing keys must be encoded using PKCS #8. To generate an RSA private key for development, the following command should get you started:
$ openssl genpkey -out privkey.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096
Update the config file and/or Docker Compose volume mounts accordingly.
If the permissions config has been defined, the actor will need access to the following actions to make the corresponding api calls. See Permissions-API for more details on updating your policy.
- iam_issuer_create
- iam_issuer_update
- iam_issuer_delete
- iam_issuer_get
- iam_issuer_list
- iam_oauthclient_create
- iam_oauthclient_delete
- iam_oauthclient_get
- iam_oauthclient_list
- iam_user_get
identity-api includes a dev container for facilitating service development. Using the dev container is not required, but provides a consistent environment for all contributors as well as a few perks like:
- gopls integration out of the box
- Host SSH auth socket mount
- Git support
To get started, you can use either VS Code or the official CLI.
In order to complete a token exchange, you will need to have an issuer configured in your database. An example seed exists in this repository and a tool exists for loading that data into the local database.
go run main.go seed-database --config identity-api.example.yaml --data data.example.yamlThe provided dev container listens for SSH connections on port 2222 and bind mounts ~/.ssh/authorized_keys from the host to facilitate SSH. In order to perform Git operations (i.e., committing code in the container), you will need to enable SSH agent forwarding from your machine to the dev container. While VS Code handles this automatically, for other editors you will need to set this up manually.
To do so, update your ~/.ssh/config to support agent forwarding. The following config snippet should accomplish this for you:
Host identity-api-devcontainer
ProxyJump YOUR_HOST_HERE
Port 2222
User vscode
ForwardAgent yes
Host YOUR_HOST_HERE
User YOUR_USER_HERE
ForwardAgent yes
See the man page for ssh_config for more information on what these options do.