Gravitee Access Management 4.13.2

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Select Gravitee Access Management 4.13.2 on Ubuntu 24.04 as the software version, choose your Region, and select Launch through EC2.

Choose m5.large, your key pair and a security group as described above. Keep the second (20 GiB) volume, because it holds the database.

Alternatively, launch with the AWS CLI. Replace the values in angle brackets:

aws ec2 run-instances --image-id <ami-id-from-the-listing> --instance-type m5.large \
  --key-name <your-key-pair> --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=gravitee-am}]'

First boot takes about two minutes after the instance is running. It creates the database, starts the management API and the gateway once to create their schemas, creates your administrator and the certificate, and then starts the stack.

Operating system SSH user

Ubuntu 24.04 ubuntu

ssh -i <your-key.pem> ubuntu@<public-ip>

systemctl is-active gravitee-am-firstboot docker gravitee-am-postgres gravitee-am-management-api gravitee-am-gateway nginx

active active active active active active

The health check does not sign in. It asks the console, the management API and the gateway for a page over HTTPS through nginx, and it verifies the instance's certificate:

sudo gravitee-am-health

PRIMARY_HEALTH_OK console=200 management-api=401(auth required) gateway=404(no domain yet)

Only SSH, HTTP, HTTPS (443) and the gateway port (8443) are public. The management API (8093) and gateway (8092) containers listen on the loopback address only, and PostgreSQL has no listener on the host at all. Check the listeners:

sudo ss -tln | grep -E ':(22|80|443|8443|8092|8093|5432) '

LISTEN 0 511 0.0.0.0:443 0.0.0.0:* LISTEN 0 4096 0.0.0.0:22 0.0.0.0:* LISTEN 0 511 0.0.0.0:80 0.0.0.0:* LISTEN 0 511 0.0.0.0:8443 0.0.0.0:* LISTEN 0 4096 127.0.0.1:8092 0.0.0.0:* LISTEN 0 4096 127.0.0.1:8093 0.0.0.0:* LISTEN 0 511 [::]:443 [::]:* LISTEN 0 4096 [::]:22 [::]:* LISTEN 0 511 [::]:80 [::]:* LISTEN 0 511 [::]:8443 [::]:*

sudo cat /root/gravitee-am-credentials.txt

The file (root-only, mode 0600) gives the console and gateway addresses, the administrator's user name and password, and the SHA-256 fingerprint of the instance's certificate:

# Gravitee Access Management 4.13.2 - written on first boot by gravitee-am-firstboot.service. Unique to this instance. GRAVITEE_AM_CONSOLE=https://ec2-13-217-163-67.compute-1.amazonaws.com/ GRAVITEE_AM_GATEWAY=https://ec2-13-217-163-67.compute-1.amazonaws.com:8443/ GRAVITEE_AM_ADMIN_USERNAME=admin GRAVITEE_AM_ADMIN_PASSWORD=<per-instance password> GRAVITEE_AM_TLS_SHA256=D7:3D:9C:DA:...:(64 hex digits in pairs)
# Sign in to the management console at GRAVITEE_AM_CONSOLE as "admin" with GRAVITEE_AM_ADMIN_PASSWORD (the only console
# account; the upstream default admin/adminadmin does not exist). Rotate it:
sudo gravitee-am-admin-password rotate
# Each security domain you create is served by the gateway at GRAVITEE_AM_GATEWAY<domain-path>/, e.g. discovery:
# ec2-13-217-163-67.compute-1.amazonaws.com:8443/<domain-path>/oidc/.well-known/openid-configuration
# Self-registration and dynamic client registration are OFF for new security domains (turn them on per domain).
# No mail server is configured (password reset / verification e-mails need your SMTP settings).
# The certificate is self-signed and unique to this instance: compare its SHA-256 fingerprint (above) with the one your
# browser shows, or install a CA-issued certificate. Do not add it to a trust store.
# Your own name (point DNS at this instance first):
sudo gravitee-am-set-hostname am.example.com
# User guide: https://secureanycloud.com/stacks/gravitee-access-management-4-13-2/

Your browser warns that the certificate is not trusted, because it was made on your instance. Compare the SHA-256 fingerprint that the browser shows with GRAVITEE_AM_TLS_SHA256 before you sign in, or use your own CA-issued certificate as described below. Do not add the certificate to a trust store.

You can also read the fingerprint from the certificate itself:

openssl x509 -in /etc/ssl/gravitee-am/gravitee-am.crt -noout -subject -fingerprint -sha256 -ext basicConstraints,subjectAltName

subject=CN = ec2-13-217-163-67.compute-1.amazonaws.com, O = sac sha256 Fingerprint=D7:3D:9C:DA:...:98:FE:29:0A X509v3 Subject Alternative Name: DNS:ec2-13-217-163-67.compute-1.amazonaws.com, IP Address:13.217.163.67, IP Address:172.31.89.127, DNS:localhost, IP Address:127.0.0.1 X509v3 Basic Constraints: critical CA:FALSE

Browse to the GRAVITEE_AM_CONSOLE address, https://<public-dns-name>/, check the certificate fingerprint, and sign in as admin with the password from the credentials file. Use the DNS name, not the IP address. nginx answers only for the instance's configured name, and an address-only request is redirected to it.

The upstream default admin / adminadmin is refused, through the console and the API alike. To check this from the instance, read your password from the root-only file into a private temporary file, so that it never appears on a command line:

umask 077;
T=$(mktemp -d) sudo sed -n 's/^GRAVITEE_AM_ADMIN_PASSWORD=//p' /root/gravitee-am-credentials.txt | tr -d '\n' | sed 's/^/admin:/' | base64 -w0 | sed 's/^/Authorization: Basic /' > "$T/basic"
D=$(sudo sed -n 's#^GRAVITEE_AM_CONSOLE=https://\([^/]*\)/#\1#p' /root/gravitee-am-credentials.txt) CA=/etc/ssl/gravitee-am/gravitee-am.crt curl -s --cacert $CA -o /dev/null -w 'administrator: HTTP %{http_code}\n' -H @"$T/basic" -X POST "https://$D/management/auth/token" curl -s --cacert $CA -o /dev/null -w 'admin / adminadmin: HTTP %{http_code}\n' -u admin:adminadmin -X POST "https://$D/management/auth/token" curl -s --cacert $CA -o /dev/null -w 'no credentials: HTTP %{http_code}\n' "https://$D/management/organizations/DEFAULT/environments/DEFAULT/domains" rm -rf "$T"

administrator: HTTP 200 admin / adminadmin: HTTP 401 no credentials: HTTP 401

A security domain is one OpenID Connect provider with its own issuer, users and applications. You can create everything below in the console: open Security domains, click Create, and then use Applications and Users in the domain.

The same steps with the management API, run from the instance, look like this. They create a domain my-company, a web application my-web-app that must use PKCE, and a user jane. The application's secret and the user's password are generated here and written to a root-only file, and nothing secret is printed:

umask 077;
T=$(mktemp -d)
D=$(sudo sed -n 's#^GRAVITEE_AM_CONSOLE=https://\([^/]*\)/#\1#p' /root/gravitee-am-credentials.txt) CA=/etc/ssl/gravitee-am/gravitee-am.crt
sudo sed -n 's/^GRAVITEE_AM_ADMIN_PASSWORD=//p' /root/gravitee-am-credentials.txt | tr -d '\n' | sed 's/^/admin:/' | base64 -w0 | sed 's/^/Authorization: Basic /' > "$T/basic" curl -s --cacert $CA -H @"$T/basic" -X POST "https://$D/management/auth/token" | jq -r '"Authorization: Bearer " + .access_token' > "$T/auth" API="https://$D/management/organizations/DEFAULT/environments/DEFAULT"
DOM=$(curl -s --cacert $CA -H @"$T/auth" -H 'Content-Type: application/json' -d '{"name":"my-company","description":"My first security domain","dataPlaneId":"default"}' "$API/domains")
DID=$(jq -r .id <<<"$DOM");
DPATH=$(jq -r .path <<<"$DOM")
curl -s --cacert $CA -H @"$T/auth" -H 'Content-Type: application/json' -X PATCH -d '{"enabled":true}' -o /dev/null "$API/domains/$DID"
IDP=$(curl -s --cacert $CA -H @"$T/auth" "$API/domains/$DID/identities" | jq -r '.[0].id') UPW="Jane-$(openssl rand -hex 12)" jq -n --arg pw "$UPW" --arg idp "$IDP" '{username:"jane",password:$pw,firstName:"Jane",lastName:"Doe",email:"jane@example.com",source:$idp,preRegistration:false}' > "$T/user.json" curl -s --cacert $CA -H @"$T/auth" -H 'Content-Type: application/json' -d @"$T/user.json" -o /dev/null -w 'user jane: HTTP %{http_code}\n' "$API/domains/$DID/users"
APP=$(curl -s --cacert $CA -H @"$T/auth" -H 'Content-Type: application/json' -d '{"name":"my-web-app","type":"WEB","redirectUris":["https://client.example.org/callback"]}' "$API/domains/$DID/applications")
AID=$(jq -r .id <<<"$APP");
CID=$(jq -r .settings.oauth.clientId <<<"$APP") jq -n --arg idp "$IDP" '{identityProviders:[{identity:$idp,priority:0}],settings:{oauth:{grantTypes:["authorization_code"],responseTypes:["code"],forcePKCE:true,redirectUris:["https://client.example.org/callback"],scopeSettings:[{scope:"openid",defaultScope:true},{scope:"profile"},{scope:"email"}]},advanced:{skipConsent:true}}}' > "$T/app.json" curl -s --cacert $CA -H @"$T/auth" -H 'Content-Type: application/json' -X PATCH -d @"$T/app.json" -o /dev/null -w 'application my-web-app: HTTP %{http_code}\n' "$API/domains/$DID/applications/$AID" { echo "DOMAIN_PATH=$DPATH"; echo "CLIENT_ID=$CID"; echo "CLIENT_SECRET=$(jq -r .settings.oauth.clientSecret <<<"$APP")"; echo "USER=jane"; echo "USER_PASSWORD=$UPW"; } | sudo tee /root/gravitee-am-my-company.txt > /dev/null
sudo chmod 600 /root/gravitee-am-my-company.txt echo "domain my-company: path $DPATH, client id $CID (secret and user password in /root/gravitee-am-my-company.txt)" rm -rf "$T"

user jane: HTTP 201 application my-web-app: HTTP 200 domain my-company: path /my-company, client id 8d8ffa37-70af-4d2d-8ffa-3770af3d2d69 (secret and user password in /root/gravitee-am-my-company.txt)

The domain's OpenID Connect discovery document is served by the gateway on port 8443. Give the gateway a few seconds to load a new domain:

D=$(sudo sed -n 's#^GRAVITEE_AM_CONSOLE=https://\([^/]*\)/#\1#p' /root/gravitee-am-credentials.txt)
P=$(sudo sed -n 's/^DOMAIN_PATH=//p' /root/gravitee-am-my-company.txt) for i in $(seq 1 30); do curl -s --cacert /etc/ssl/gravitee-am/gravitee-am.crt -o /dev/null -f "https://$D:8443$P/oidc/.well-known/openid-configuration" && break; sleep 3; done curl -s --cacert /etc/ssl/gravitee-am/gravitee-am.crt "https://$D:8443$P/oidc/.well-known/openid-configuration" | jq '{issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, code_challenge_methods_supported}'

{ "issuer": "https://ec2-13-217-163-67.compute-1.amazonaws.com:8443/my-company/oidc", "authorization_endpoint": "https://ec2-13-217-163-67.compute-1.amazonaws.com:8443/my-company/oauth/authorize", "token_endpoint": "https://ec2-13-217-163-67.compute-1.amazonaws.com:8443/my-company/oauth/token", "userinfo_endpoint": "https://ec2-13-217-163-67.compute-1.amazonaws.com:8443/my-company/oidc/userinfo", "jwks_uri": "https://ec2-13-217-163-67.compute-1.amazonaws.com:8443/my-company/oidc/.well-known/jwks.json", "code_challenge_methods_supported": [ "plain", "S256" ] }

In the console, the domain now lists the application and the user:

Your application sends the user's browser to the domain's authorization endpoint on port 8443, and the gateway shows its hosted sign-in page. There is no "sign up" link, because self-registration is off:

The image includes an end-to-end check that runs the whole flow the way an application does, over HTTPS through nginx with the instance's certificate verified. The check performs these actions:

• Creates a temporary security domain, a web application that requires PKCE and a user.
• Signs the user in on the gateway's login page, exchanges the authorization code for tokens and calls userinfo.
• Checks that a second use of the same code, a request without PKCE and a wrong password are refused.
• Checks that anonymous dynamic client registration is refused and that self-registration is off.
• Deletes the temporary domain.

The check prints no token or secret:

sudo gravitee-am-cred-roundtrip.sh

GRAVITEE_AM_ROUNDTRIP_OK admin=200 wrong-default-empty=401 dcr=403 self-registration=refused no-pkce=invalid_request wrong-user-password=refused flow=login>code>token>userinfo pkce=S256-required code-reuse=invalid_grant id_token=RS256 issuer=pinned

Anonymous OAuth dynamic client registration (RFC 7591) and self-registration are refused on every new domain:

D=$(sudo sed -n 's#^GRAVITEE_AM_CONSOLE=https://\([^/]*\)/#\1#p' /root/gravitee-am-credentials.txt)
P=$(sudo sed -n 's/^DOMAIN_PATH=//p' /root/gravitee-am-my-company.txt)
C=$(sudo sed -n 's/^CLIENT_ID=//p' /root/gravitee-am-my-company.txt)
curl -s --cacert /etc/ssl/gravitee-am/gravitee-am.crt -o /dev/null -w 'anonymous client registration: HTTP %{http_code}\n' -H 'Content-Type: application/json' -d '{"redirect_uris":["https://attacker.example/cb"],"client_name":"probe"}' "https://$D:8443$P/oidc/register" if
curl -s --cacert /etc/ssl/gravitee-am/gravitee-am.crt -L "https://$D:8443$P/register?client_id=$C" | grep -q 'name="email"'; then echo 'self-registration: form served'; else echo 'self-registration: refused (error page)'; fi

anonymous client registration: HTTP 403 self-registration: refused (error page)

The services and every container are blocked from the instance metadata service. From inside the gateway container, as its own user, a request to the metadata address times out, while a request to the gateway itself answers with a 404, because no domain lives at its root:

sudo docker exec gam-gateway sh -c 'wget -q -T 5 -O /dev/null http://169.254.169.254/latest/meta-data/ 2>/dev/null && echo "metadata: reachable" || echo "metadata: blocked"; echo "gateway control:$(wget -S -q -T 5 -O /dev/null http://127.0.0.1:8092/ 2>&1 | head -1)"'

metadata: blocked gateway control: HTTP/1.1 404 Not Found

The containers run unprivileged, and no secret is in any container's configuration. The environment holds only paths, locale and Java memory settings, and the secrets are in root-owned files mounted read-only:

sudo docker inspect gam-management-api gam-gateway gam-postgres --format '{{.Name}} user={{.Config.User}} readonly={{.HostConfig.ReadonlyRootfs}} capdrop={{.HostConfig.CapDrop}} privileged={{.HostConfig.Privileged}}'
sudo docker inspect gam-management-api gam-gateway gam-postgres --format '{{range .Config.Env}}{{println .}}{{end}}' | cut -d= -f1 | grep . | sort -u | tr '\n' ' '; echo

/gam-management-api user=997:986 readonly=true capdrop=[ALL] privileged=false /gam-gateway user=997:986 readonly=true capdrop=[ALL] privileged=false /gam-postgres user=70:70 readonly=true capdrop=[ALL] privileged=false DOCKER_PG_LLVM_DEPS GIO_MAX_MEM GIO_MIN_MEM GOSU_VERSION GRAVITEE_AM_HOME JAVA_HOME JAVA_OPTS LANG LANGUAGE LC_ALL NO_COLOR PATH PGDATA PG_MAJOR PG_SHA256 PG_VERSION POSTGRES_HOST_AUTH_METHOD POSTGRES_INITDB_ARGS POSTGRES_USER

Point a DNS record (for example am.example.com) at the instance's public IP address, and then set the name. This command updates nginx, the console and API, the gateway's issuer and the links in the credentials file, and it makes a new self-signed certificate for the name:

sudo gravitee-am-set-hostname am.example.com

Security domains that you created before the change keep their users and applications. Their issuer follows the new name (https://am.example.com:8443/<domain-path>/oidc), so update the issuer and redirect URLs that your applications use.

To use a CA-issued certificate instead, replace /etc/ssl/gravitee-am/gravitee-am.crt (full chain) and /etc/ssl/gravitee-am/gravitee-am.key (the key, mode 0600). Then run sudo systemctl reload nginx. To see the current name and certificate, run the following:

sudo gravitee-am-set-hostname --show

name: ec2-13-217-163-67.compute-1.amazonaws.com console: https://ec2-13-217-163-67.compute-1.amazonaws.com/ gateway: https://ec2-13-217-163-67.compute-1.amazonaws.com:8443/<domain>/oidc/.well-known/openid-configuration also served: ec2-13-217-163-67.compute-1.amazonaws.com 13.217.163.67 172.31.89.127 certificate: SHA-256 D7:3D:9C:DA:...:98:FE:29:0A

The administrator is an account defined in the management API's configuration, and only its bcrypt hash is stored. Change its password with the image's helper. The helper generates a new random password, restarts the management API and writes the new password to /root/gravitee-am-credentials.txt:

sudo gravitee-am-admin-password rotate