https://github.com/ssoready/ssoready-java
Java SDK for SSOReady. Add SAML + SCIM support to any Java application this afternoon.
https://github.com/ssoready/ssoready-java
java saml scim sso
Last synced: 9 months ago
JSON representation
Java SDK for SSOReady. Add SAML + SCIM support to any Java application this afternoon.
- Host: GitHub
- URL: https://github.com/ssoready/ssoready-java
- Owner: ssoready
- License: mit
- Created: 2024-10-10T23:04:24.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-05T19:32:47.000Z (about 1 year ago)
- Last Synced: 2025-03-25T14:03:45.518Z (10 months ago)
- Topics: java, saml, scim, sso
- Language: Java
- Homepage: https://ssoready.com
- Size: 105 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SSOReady-Java: SAML & SCIM for Java
[](https://central.sonatype.com/artifact/com.ssoready/ssoready-java)
`com.ssoready:ssoready-java` is a Java SDK for the [SSOReady](https://ssoready.com) API.
SSOReady is a set of open-source dev tools for implementing Enterprise SSO. You
can use SSOReady to add SAML and SCIM support to your product this afternoon.
For example applications built using SSOReady-Java, check out:
- [SSOReady Example App: Java Spring Boot with SAML](https://github.com/ssoready/ssoready-example-app-java-spring-boot-saml)
## Installation
With `build.gradle`:
```groovy
dependencies {
implementation 'com.ssoready:ssoready-java:1.0.0'
}
```
With `pom.xml`:
```xml
com.ssoready
ssoready-java
1.0.0
```
## Usage
This section provides a high-level overview of how SSOReady works, and how it's
possible to implement SAML and SCIM in just an afternoon. For a more thorough
introduction, visit the [SAML
quickstart](https://ssoready.com/docs/saml/saml-quickstart) or the [SCIM
quickstart](https://ssoready.com/docs/scim/scim-quickstart).
The first thing you'll do is create a SSOReady client instance:
```java
import com.ssoready.api.SSOReady;
// this loads your SSOReady API key from SSOREADY_API_KEY
SSOReady ssoready = SSOReady.builder().build();
```
### SAML in two lines of code
SAML (aka "Enterprise SSO") consists of two steps: an _initiation_ step where
you redirect your users to their corporate identity provider, and a _handling_
step where you log them in once you know who they are.
To initiate logins, you'll use SSOReady's [Get SAML Redirect
URL](https://ssoready.com/docs/api-reference/saml/get-saml-redirect-url)
endpoint:
```java
// this is how you implement a "Sign in with SSO" button
String redirectUrl = ssoready.saml().getSamlRedirectUrl(
GetSamlRedirectUrlRequest
.builder()
// the ID of the organization/workspace/team (whatever you call it)
// you want to log the user into
.organizationExternalId(email.split("@")[1])
.build()
).getRedirectUrl().orElseThrow();
// redirect the user to `redirectUrl`...
```
You can use whatever your preferred ID is for organizations (you might call them
"workspaces" or "teams") as your `organizationExternalId`. You configure those
IDs inside SSOReady, and SSOReady handles keeping track of that organization's
SAML and SCIM settings.
To handle logins, you'll use SSOReady's [Redeem SAML Access
Code](https://ssoready.com/docs/api-reference/saml/redeem-saml-access-code) endpoint:
```java
// this goes in your handler for POST /ssoready-callback
RedeemSamlAccessCodeResponse redeemResponse = this.ssoready.saml().redeemSamlAccessCode(
RedeemSamlAccessCodeRequest
.builder()
.samlAccessCode("saml_access_code_...")
.build()
);
// log the user in as `redeemResponse.getEmail()` inside `redeemResponse.getOrganizationExternalId()`...
```
You configure the URL for your `/ssoready-callback` endpoint in SSOReady.
### SCIM in one line of code
SCIM (aka "Enterprise directory sync") is basically a way for you to get a list
of your customer's employees offline.
To get a customer's employees, you'll use SSOReady's [List SCIM
Users](https://ssoready.com/docs/api-reference/scim/list-scim-users) endpoint:
```java
ListScimUsersResponse listScimUsersResponse = ssoready.scim().listScimUsers(
ScimListScimUsersRequest
.builder()
.organizationExternalId("...")
.build()
);
// create users from each scimUser
for (ScimUser scimUser : listScimUsersResponse.getScimUsers().orElseThrow()) {
// every scimUser has getId(), getEmail(), getAttributes(), and getDeleted()
scimUser.getEmail();
}
```
## Contributing
Issues and PRs are more than welcome. Be advised that this library is largely
autogenerated from [`ssoready/docs`](https://github.com/ssoready/docs). Most
code changes ultimately need to be made there, not on this repo.