{"id":23125105,"url":"https://github.com/statisticsnorway/guardian-client-java","last_synced_at":"2025-07-02T06:06:10.330Z","repository":{"id":40564432,"uuid":"455707422","full_name":"statisticsnorway/guardian-client-java","owner":"statisticsnorway","description":"Java client library for retrieving access tokens from Maskinporten Guardian","archived":false,"fork":false,"pushed_at":"2024-10-30T12:45:59.000Z","size":89,"stargazers_count":2,"open_issues_count":8,"forks_count":1,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-05T00:11:14.225Z","etag":null,"topics":["dapla","skyinfrastruktur"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statisticsnorway.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-04T21:52:47.000Z","updated_at":"2024-10-30T12:46:01.000Z","dependencies_parsed_at":"2024-10-30T12:35:34.933Z","dependency_job_id":null,"html_url":"https://github.com/statisticsnorway/guardian-client-java","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/statisticsnorway/guardian-client-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statisticsnorway%2Fguardian-client-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statisticsnorway%2Fguardian-client-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statisticsnorway%2Fguardian-client-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statisticsnorway%2Fguardian-client-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statisticsnorway","download_url":"https://codeload.github.com/statisticsnorway/guardian-client-java/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statisticsnorway%2Fguardian-client-java/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263083591,"owners_count":23411163,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dapla","skyinfrastruktur"],"created_at":"2024-12-17T08:12:33.732Z","updated_at":"2025-07-02T06:06:10.300Z","avatar_url":"https://github.com/statisticsnorway.png","language":"Java","readme":"# Guardian Client\n\nJava client library for retrieving access tokens from [maskinporten-guardian](https://github.com/statisticsnorway/maskinporten-guardian).\nIt also provides a CLI if you want to use it from the command line.\n\n[Maskinporten Guardian](https://github.com/statisticsnorway/maskinporten-guardian) allows SSB services and\ntrusted users to retrieve Maskinporten access tokens. It relies on keycloak to authorize the\nusers.\n\n## Why?\n\n* _YOLO_ - No need to learn about the Maskinporten Guardian API. Just retrieve them tokens and get on with your life.\n* The Guardian Client maintains a local cache of keycloak and maskinporten tokens and provides a means for\n  automatically re-fetching tokens only when they need to be retrieved. Reduces chattiness and\n  unnecessary network traffic.\n* Keeps track of default service locations - just let `guardian-client` know which environment you're running within.\n* Use either as a library or from the command line\n* No transitive dependencies - `guardian-client` only requires the JDK (11).\n* You're lazy. Lazy is good :)\n\nWhen accessing Maskinporten Guardian as a service user (the preferred way), `guardian-client` will\nautomatically retrieve and refresh the required keycloak access token if you configure the keycloak client secret.\n\n## Getting started\n\n#### Maven\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eno.ssb.guardian\u003c/groupId\u003e\n    \u003cartifactId\u003eguardian-client\u003c/artifactId\u003e\n    \u003cversion\u003e[version]\u003c/version\u003e\n    \u003cscope\u003ecompile\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n#### Gradle\n```\nimplementation 'no.ssb.guardian:guardian-client:[version]'\n```\n\n## Usage\n\nInstantiate the Guardian client:\n\n```java\n    GuardianClient client = GuardianClient.withConfig()\n    .environment(STAGING)\n    .maskinportenClientId(\"some-uuid\")\n    .keycloakClientSecret(\"some-secret\")\n    .create();\n```\n\nRetrieve maskinporten token:\n\n```java\n    String accessToken = client.getMaskinportenAccessToken(\"some:scope1\", \"some:scope2\");\n```\n\n## Configuration options\n\n| Key                               | Description                                                                                                                                                                                        |                                        Default |\n|-----------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------:|\n| maskinportenClientId              | Maskinporten client ID from samhandlingsportalen - typically a UUID.                                                                                                                               |                                              - |\n| environment                       | Optionally denotes the runtime environment (`PROD`, `STAGING` or `LOCAL`) the Guardian Client is working with. By specifying this you can rely on default values for guardianUrl and keycloakUrl   |                                              - |\n| guardianUrl                       | Root URL of the maskinporten-guardian server (not needed if you specify `environment`)                                                                                                             |                                              - |\n| keycloakUrl                       | Root URL of the keycloak server (not needed if you specify `environment`)                                                                                                                          |                                              - |\n| keycloakTokenEndpoint             | Path to the token endpoint of the keycloak server. Only required if you're using a non-standard endpoint                                                                                           | /auth/realms/ssb/protocol/openid-connect/token |\n| keycloakClientId                  | Keycloak client credentials id for the keycloak service user. *You will typically want to rely on the default value for this.*                                                                     |        maskinporten-`\u003cmaskinporten client id\u003e` |\n| keycloakClientSecret              | Keycloak client credentials secret for the maskinporten keycloak service user. Only needed for service users.                                                                                      |                                              - |\n| staticKeycloakToken               | Configure if you want to explicitly use a specific keycloak token. Note that you are responsible for making sure the provided keycloak token is valid (not expired) and refreshed whenever needed. |                                              - |\n| shortenedTokenExpirationInSeconds | The number of seconds actual token expiration time that the caches will use to determine whether or not a token needs to be refetched.                                                             |                                300 (5 minutes) |\n\n\n\n## Using the Guardian Client CLI\n\nIn addition to being a java client library, the Guardian Client can be used from the command line.\n\n```sh\n$ guardian-client --help\n\nUsage: guardian-client [-hvV] [-e=\u003cenvironment\u003e] -u=\u003cmaskinportenClientId\u003e\n                       [-s=\u003cscopes\u003e[,\u003cscopes\u003e...]]...\n                       (-p=\u003cmaskinportenClientSecret\u003e |\n                       -t=\u003cstaticKeycloakToken\u003e)\nRetrieve access tokens from Maskinporten Guardian\n  -e, --env=\u003cenvironment\u003e   Runtime environment (PROD, STAGING or LOCAL) the\n                              Guardian Client is working with\n                              Default: STAGING\n  -h, --help                Show this help message and exit.\n  -p, --keycloak-client-secret=\u003cmaskinportenClientSecret\u003e\n                            Keycloak client secret (needed if Guardian client\n                              should fetch keycloak token)\n  -s, --scopes=\u003cscopes\u003e[,\u003cscopes\u003e...]\n                            Comma-separated list of maskinporten scopes (e.g.\n                              some:scope1,some:scope2)\n  -t, --keycloak-token=\u003cstaticKeycloakToken\u003e\n                            Keycloak token\n  -u, --maskinporten-client-id=\u003cmaskinportenClientId\u003e\n                            Maskinporten client ID\n  -v, --verbose             Shows what's going on under the hood\n  -V, --version             Print version information and exit.\n```\n\nWe recommend that you invoke the CLI application using the [guardian-client shell wrapper](bin/guardian-client).\nAlso, make sure to configure the `GUARDIAN_CLIENT_JAR` environment variable, pointing at the\nguardian-client jar file.\n\n### Install the Guardian Client CLI locally\n\nIf you want to use the Guardian Client CLI from \"anywhere\":\n* The [guardian-client shell wrapper](bin/guardian-client) must be on your path\n* Set the `GUARDIAN_CLIENT_JAR` environment variable to point at the guardian-client jar file\n\n*Example config (.bashrc/.zsh):*\n```\nexport GUARDIAN_CLIENT_HOME=path/to/guardian-client-java\nexport GUARDIAN_CLIENT_JAR=$GUARDIAN_CLIENT_HOME/target/guardian-client-*.jar\nexport PATH=:$GUARDIAN_CLIENT_HOME/bin:$PATH\n```\n\n### Example: Run the CLI as a service user\n```sh\n$ guardian-client --verbose \\\n   --env STAGING \\\n   --maskinporten-client-id \u003cmaskinporten client id\u003e \\\n   --keycloak-client-secret \u003ckeycloak client secret\u003e  \\\n   --scopes some:scope1,some:scope2\n```\n\n### Example: Run the CLI with static (e.g. personal) keycloak token\n```sh\n$ guardian-client --verbose \\\n   --env STAGING \\\n   --maskinporten-client-id \u003cmaskinporten client id\u003e \\\n   --keycloak-token \u003cey...\u003e \\\n   --scopes some:scope1,some:scope2\n```\n\n### Run CLI examples using `make`\n\nThe above examples can be run using _Make_. Create a `.env` file with your\nsettings (see the `.env-example` file). Then:\n\n```sh\nmake run-cli-as-service-user\n```\n\nor\n\n```sh\nmake run-cli-with-static-keycloak-token\n```\n\n## Development\n\nUse `make` for common tasks:\n\n```\nbuild-mvn                            Build project and install to you local maven repo\nrun-cli-help                         Run CLI --help\nrun-cli-as-service-user              Run the CLI as a service user\nrun-cli-with-static-keycloak-token   Run the CLI with an explicit keycloak token (can be used for personal users)\nrelease-dryrun                       Simulate a release to detect any issues\nrelease                              Release a new version. Update POMs and tag the new version in git\n```\n\n## Prerequisites\n\nJDK 11\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatisticsnorway%2Fguardian-client-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatisticsnorway%2Fguardian-client-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatisticsnorway%2Fguardian-client-java/lists"}