Categories
Development Java

OneLogin API-Zugriff mit Java

Im vorherigen Post haben wir gesehen, dass ein neuer Benutzer sich selbst registrieren kann, aber um den Zugang zur Anwendung zu erhalten, er noch durch einen User-Admin freigeschaltet/der Anwendung hinzugefügt werden muss.

Das Hinzufügen des Benutzers erfolgt in OneLogin, so dass der User-Admin auch in diesem Tool geschult werden müsste.

Um den Schulungsaufwand zu vermeiden und ein flüssigeres Arbeiten, ohne Wechsel der Anwendungen, zu ermöglichen, wollen wir einige Funktionalität von OneLogin in unserer Anwendung ermöglichen. Dazu gibt es in OneLogin eine API-Schnittstelle, die wir mit einem Java-Client ansteuern werden.

Der Java-Client logt sich einmalig mit Client ID und Secret (API Credentials! siehe unten) ein und erhält so ein Access Token, mit dem die weiteren API-Funktionen ausgeführt werden können.

Die API-Dokumentation, für Version 2, findet sich hier: https://developers.onelogin.com/api-docs/2/getting-started/dev-overview

Vorbereitung / Daten sammeln

API-Subdomain

Die API-Domain des Testprojekt ist: deringo-dev.onelogin.com

Die API-Sub-Domain lautet foglich: deringo-dev

API ID & Secret

Für die Benutzung der API wird Client ID und Client Secret benötigt. Das kennen wir schon aus einem vorherigen Post zu OneLogin:

Für den Zugriff über die API benötigen wir aber ein anderes Client ID & Secret Paar! Dieses findet sich in dem Developers-Tab unter API Credentials.

Dort ist ein entsprechender Zugang einzurichten, für das Test-Projekt haben wir mit Manage All eingerichtet:

OneLogin App ID

Die ID unserer Test-Anwendung findet sich in der URL nachdem man auf Applications -> Applications die App auswählt, in unserem Beispiel "1739301":

Java Programm aufsetzen

Abhängigkeiten

Das Projekt wird für Java 8 aufgesetzt und benötigt Apache HttpClient 4.5 und Json:

<properties>
  <maven.compiler.source>8</maven.compiler.source>
  <maven.compiler.target>8</maven.compiler.target>
</properties>

<dependencies>
  <!-- https://mvnrepository.com/artifact/org.apache.httpcomponents/httpclient -->
  <dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.13</version>
  </dependency>
  <!-- https://mvnrepository.com/artifact/org.json/json -->
  <dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20220320</version>
  </dependency>
</dependencies>

Programm Rumpf

Zum Testen der API-Funktionen wird eine Test-Klasse mit den oben gesammelten Informationen angelegt und dann jeweils eine eigene Methode in der Klasse verwendet.

public class TestMain {

	private static final String ONELOGIN_SUBDOMAIN = "deringo-dev";
	
	// OneLogin Administration -> Applications -> select Application, get ID from URL
	private static final String ONELOGIN_APP_ID = "1739301";
	
	// OneLogin Administration -> Developers -> API Credentials
	private static final String ONELOGIN_CLIENT_ID = "12345<geheim>67890";
	private static final String ONELOGIN_CLIENT_SECRET = "12345<geheim>67890";
	
	
	public static void main(String[] args) {
		TestMain main = new TestMain();

		main.sayHello();
	}

	private void sayHello() {
		System.out.println("Hello World!");
	}
}

Access Token

Für die API Calls wird ein Access Token benötigt, wie dieser zu bekommen ist ist hier beschrieben: Generate OAuth 2.0 Tokens v2| OneLogin Developers

private String getAccessToken() {

  CloseableHttpClient client = HttpClientBuilder.create().build();

  HttpPost request = new HttpPost(String.format("https://%%s.onelogin.com/auth/oauth2/v2/token", ONELOGIN_SUBDOMAIN));

  String credentials = String.format("%%s:%%s", ONELOGIN_CLIENT_ID, ONELOGIN_CLIENT_SECRET);
  byte[] encodedAuth = Base64.getEncoder().encode(credentials.getBytes());
  String authHeader = "Basic " + new String(encodedAuth);

  request.setHeader("Authorization", authHeader);
  request.addHeader("Content-Type", "application/json");
  request.setEntity(new StringEntity("{ \"grant_type\": \"client_credentials\" }", "UTF-8"));

  try {
    CloseableHttpResponse reponse = client.execute(request);

    String content = EntityUtils.toString(reponse.getEntity());

    JSONObject json = new JSONObject(content);

    String accessToken = json.getString("access_token");
    return accessToken;

  } catch (IOException e) {
    e.printStackTrace();
    return null;
  }
}

List App Users

Use this API to return a list of users that are assigned to an App.

Doku: List App Users - OneLogin API

Sample Code:

private void listAppUsers() {
  String resourceURL = String.format("https://%%s.onelogin.com/api/2/apps/%%s/users", ONELOGIN_SUBDOMAIN, ONELOGIN_APP_ID);

  CloseableHttpClient client = HttpClientBuilder.create().build();

  HttpGet request = new HttpGet(resourceURL);
  request.setHeader("Authorization", "bearer " + getAccessToken());
  request.addHeader("Content-Type", "application/json");

  try {
    CloseableHttpResponse reponse = client.execute(request);

    String content = EntityUtils.toString(reponse.getEntity());

    JSONArray jsonArray = new JSONArray(content);
    jsonArray.forEach(o -> System.out.println(o));

  } catch (IOException e) {
    e.printStackTrace();
  }
}

List Roles

Use this API to return a list of roles.
This endpoint supports pagination and sorting.

Doku: List Roles (onelogin.com)

private void listRoles() {
  String resourceURL = String.format("https://%%s.onelogin.com/api/2/roles", ONELOGIN_SUBDOMAIN);

  CloseableHttpClient client = HttpClientBuilder.create().build();

  HttpGet request = new HttpGet(resourceURL);
  request.setHeader("Authorization", "bearer " + getAccessToken());
  request.addHeader("Content-Type", "application/json");

  try {
    CloseableHttpResponse reponse = client.execute(request);

    String content = EntityUtils.toString(reponse.getEntity());

    JSONArray jsonArray = new JSONArray(content);
    jsonArray.forEach(o -> System.out.println(o));

  } catch (IOException e) {
    e.printStackTrace();
  }
}

Wenn zB nur die Rollen für unsere Test-App angezeigt werden sollen und der Rollen Name ein "u" enthalten muss, setzt sich der resourceURL-String wie folgt zusammen:

String resourceURL = String.format("https://%%s.onelogin.com/api/2/roles?app_id=%%s&name=u", ONELOGIN_SUBDOMAIN, ONELOGIN_APP_ID);

Query Parameter

Es gibt Query Parameter, die anscheinend von vielen Funktionen unterstützt werden: Fields, Search, Pagination & Sort

Doku: Using Query Parameters - OneLogin Developers

Als Beispiel erweitern wir das List App Users Beispiel indem wir lediglich die resourceURL anpassen und für die Query Parameter vorbereiten:

String queryParameter = "";
String resourceURL = String.format("https://%%s.onelogin.com/api/2/apps/%%s/users%%s", ONELOGIN_SUBDOMAIN, ONELOGIN_APP_ID, queryParameter);

Wollen wir uns anstelle der gesamten User-Information lediglich Vor- und Nachname zurückgeben lassen, neben der ID, dann brauchen wir lediglich den Query Parameter anpassen:

String queryParameter = "?fields=firstname,lastname";

Suche nach allen Benutzern mit dem Nachnamen "Mustermann":

String queryParameter = "?lastname=Mustermann";

Was NICHT funktioniert: Suche nach allen Benutzern mit dem Nachnamen "Mustermann" und dem Vornamen "Erika":

// funktioniert NICHT:
String queryParameter = "?lastname=Mustermann,firstname=Erika";

Ups, eigene Dummheit, wenn man es richtig macht, dann geht es; Die Parameter werden natürlich mit einem "&" concatiniert und nicht mit einem ",":

// funktioniert NICHT:
String queryParameter = "?lastname=Mustermann&firstname=Erika";

Alle Benutzer mit Vorname "Erika", der Nachname soll mit "Muster" anfangen und wir brauchen nur Vor- und Nachname:

String queryParameter = "?lastname=Muster*&firstname=Erika&fields=firstname,lastname";

Seite 1 alle Benutzer, absteigend sortiert nach Nachnamen, bei einer Seitengröße von 1:

String queryParameter = "?page=1&limit=1&sort=-lastname";

Seitenweises Vor- oder Zurückblättern ist möglich, dazu gibt es den Parameter "cursor". Im Header der ersten Paginierten Response gibt es, falls vorhanden, After-Curser und Before-Curser. Über diese Werte kann vor- und zurückgeblättert werden.

Beispielsweise um die erste Seite zu erhalten und anschließend eine Seite weiter blättern:

// erster Aufruf:
String queryParameter = "?page=1&limit=1";
[...]
String afterCursor = response.getFirstHeader("After-Cursor").getValue();
[...]

// zweiter Aufruf
queryParameter = "?cursor=" + afterCursor;

kleines User Management

Es soll zuerst ein neuer User angelegt werden. Anschließend bearbeitet, der Anwendung hinzugefügt und wieder entfernt und abschließend gelöscht werden.

Create User

Doku: Create User - OneLogin Developers

Erstmal ein minimales Beispiel:

private void createUser() throws Exception {
  String resourceURL = String.format("https://%%s.onelogin.com/api/2/users", ONELOGIN_SUBDOMAIN);

  CloseableHttpClient client = HttpClientBuilder.create().build();

  HttpPost request = new HttpPost(resourceURL);
  request.setHeader("Authorization", "bearer " + getAccessToken());
  request.addHeader("Content-Type", "application/json");

  String json = "{\"username\":\"min.requirements\"}";
  StringEntity entity = new StringEntity(json);
  request.setEntity(entity);

  try {
    CloseableHttpResponse response = client.execute(request);
    System.out.println(response.getStatusLine());
    String content = EntityUtils.toString(response.getEntity());
    System.out.println(content);
    JSONObject o = new JSONObject(content);
    System.out.println("new User ID: " + o.get("id"));
  } catch (IOException e) {
    e.printStackTrace();
  }
}

Consolen Ausgabe:

HTTP/1.1 201 Created
{"firstname":null,"updated_at":"2022-06-01T14:34:52.423Z","role_ids":[],"invitation_sent_at":null,"member_of":null,"distinguished_name":null,"email":null,"id":178924216,"password_changed_at":null,"manager_ad_id":null,"group_id":null,"invalid_login_attempts":0,"phone":null,"title":null,"preferred_locale_code":null,"department":null,"samaccountname":null,"lastname":null,"custom_attributes":{"my_role":null},"created_at":"2022-06-01T14:34:52.423Z","directory_id":null,"locked_until":null,"status":7,"company":null,"activated_at":null,"last_login":null,"trusted_idp_id":null,"manager_user_id":null,"username":"min.requirements","comment":null,"external_id":null,"state":1,"userprincipalname":null}
new User ID: 178924216

Nächstes Beispiel mit Vor-, Nach- und Usernamen, Passwort und schönerem JSON:

private void createUser() throws Exception {
  String resourceURL = String.format("https://%%s.onelogin.com/api/2/users", ONELOGIN_SUBDOMAIN);

  CloseableHttpClient client = HttpClientBuilder.create().build();

  HttpPost request = new HttpPost(resourceURL);
  request.setHeader("Authorization", "bearer " + getAccessToken());
  request.addHeader("Content-Type", "application/json");

  JSONObject json = new JSONObject()
    .put("firstname", "Happy")
    .put("lastname", "Gilmore")
    .put("username", "happy.gilmore")
    .put("password", "helloworld123")
    .put("password_confirmation", "helloworld123");
  StringEntity entity = new StringEntity(json.toString());
  request.setEntity(entity);

  try {
    CloseableHttpResponse response = client.execute(request);
    System.out.println(response.getStatusLine());
    String content = EntityUtils.toString(response.getEntity());
    System.out.println(content);
    JSONObject o = new JSONObject(content);
    System.out.println("new User ID: " + o.get("id"));
  } catch (IOException e) {
    e.printStackTrace();
  }
}

HTTP/1.1 201 Created
{"firstname":"Happy","updated_at":"2022-06-01T14:43:30.646Z","role_ids":[],"invitation_sent_at":null,"member_of":null,"distinguished_name":null,"email":null,"id":178924824,"password_changed_at":"2022-06-01T14:43:30.629Z","manager_ad_id":null,"group_id":null,"invalid_login_attempts":0,"phone":null,"title":null,"preferred_locale_code":null,"department":null,"samaccountname":null,"lastname":"Gilmore","custom_attributes":{"my_role":null},"created_at":"2022-06-01T14:43:30.646Z","directory_id":null,"locked_until":null,"status":1,"company":null,"activated_at":"2022-06-01T14:43:30.644Z","last_login":null,"trusted_idp_id":null,"manager_user_id":null,"username":"happy.gilmore","comment":null,"external_id":null,"state":1,"userprincipalname":null}
new User ID: 178924824

Unser neuer User Happy Gilmore ist angelegt und kann sich mit seinem Username & Passwort auch anmelden, kommt aber, wie erwartet, noch nicht auf die Anwendung, da er ihr noch nicht zugewiesen wurde:

Update User

Doku: Update User - OneLogin Developers

private void updateUser(Integer id) throws Exception {
  String resourceURL = String.format("https://%%s.onelogin.com/api/2/users/%%d", ONELOGIN_SUBDOMAIN, id);

  CloseableHttpClient client = HttpClientBuilder.create().build();

  HttpPut request = new HttpPut(resourceURL);
  request.setHeader("Authorization", "bearer " + getAccessToken());
  request.addHeader("Content-Type", "application/json");

  JSONObject json = new JSONObject()
    .put("firstname", "Very Happy");
  StringEntity entity = new StringEntity(json.toString());
  request.setEntity(entity);

  try {
    CloseableHttpResponse response = client.execute(request);
    System.out.println(response.getStatusLine());
    String content = EntityUtils.toString(response.getEntity());
    System.out.println(content);
    JSONObject o = new JSONObject(content);
    System.out.println("User ID: " + o.get("id"));
    System.out.println("Firstname: " + o.get("firstname"));
  } catch (IOException e) {
    e.printStackTrace();
  }
}

HTTP/1.1 200 OK
{"firstname":"Very Happy","state":1,"manager_user_id":null,"department":null,"comment":null,"created_at":"2022-06-01T14:43:30.646Z","email":null,"last_login":"2022-06-01T14:46:10.795Z","lastname":"Gilmore","activated_at":"2022-06-01T14:43:30.644Z","directory_id":null,"updated_at":"2022-06-01T14:57:22.656Z","group_id":null,"samaccountname":null,"status":1,"userprincipalname":null,"trusted_idp_id":null,"title":null,"manager_ad_id":null,"invalid_login_attempts":0,"locked_until":null,"phone":null,"role_ids":[],"invitation_sent_at":null,"company":null,"distinguished_name":null,"external_id":null,"password_changed_at":"2022-06-01T14:43:30.629Z","preferred_locale_code":null,"id":178924824,"member_of":null,"username":"happy.gilmore","custom_attributes":{"my_role":null}}
User ID: 178924824
Firstname: Very Happy

User einer Anwendung hinzufügen

Als nächstes sollte der User einer Anwendung hinzugefügt werden, um so den Zugang zu gewähren.

Überraschenderweise gibt es aber keine API, um einer App einen User hinzuzufügen. irgendwie ist das nicht ganz nachzuvollziehen, da dies über die OneLogin-Webseite möglich ist und es einen API Call gibt, um alle User einer App anzeigen zu lassen (List App Users - OneLogin API).

Ein Erklärungs- und somit Lösungsansatz lautet:

The proper way to do this is to assign applications to a Role in the admin console and then use the APIs to set the roles for the user.

This, in turn grants the user access to the application assigned to the role.

java - Onelogin API to add applications to user - Stack Overflow

Wir haben ja noch die Rolle "user", der die App zugeordnet ist, aus einem vorhergehendem Versuch. Die sollten wir nehmen können.

Man kann es im Screenshot nicht sehen, aber in der URL ist die ID der Rolle enthalten: 546920

Add User to Role

Doku: Add Role Users - OneLogin API

private void addUserToRole(Integer roleId, Integer userId) throws Exception {
  String resourceURL = String.format("https://%%s.onelogin.com/api/2/roles/%%d/users", ONELOGIN_SUBDOMAIN, roleId);

  CloseableHttpClient client = HttpClientBuilder.create().build();

  HttpPost request = new HttpPost(resourceURL);
  request.setHeader("Authorization", "bearer " + getAccessToken());
  request.addHeader("Content-Type", "application/json");

  StringEntity entity = new StringEntity("[" + userId + "]");
  request.setEntity(entity);

  try {
    CloseableHttpResponse response = client.execute(request);
    System.out.println(response.getStatusLine());
    String content = EntityUtils.toString(response.getEntity());
    System.out.println(content);
  } catch (IOException e) {
    e.printStackTrace();
  }
}

HTTP/1.1 200 OK
[{"id":178924824}

Die Überprüfung in der OneLogin Webseite ergibt, dass der User in der Tat hinzugefügt wurde, und es wurden auch keine vorhandenen User aus der Rolle entfernt, die nicht in dem Array enthalten waren.

Unser neuer User Happy Gilmore ist angelegt und kann sich mit seinem Username & Passwort auch anmelden, kommt jetzt auf die Anwendung, da er ihr über die Rolle "user" zugewiesen wurde:

Remove User from Role

Doku: Remove Role Users - OneLogin API

private void removeUserFromRole(Integer roleId, Integer userId) throws Exception {
  String resourceURL = String.format("https://%%s.onelogin.com/api/2/roles/%%d/users", ONELOGIN_SUBDOMAIN, roleId);

  CloseableHttpClient client = HttpClientBuilder.create().build();

  HttpPost request = new HttpPost(resourceURL) {
    @Override
    public String getMethod() {
      return "DELETE";
    }
  };
  request.setHeader("Authorization", "bearer " + getAccessToken());
  request.addHeader("Content-Type", "application/json");

  StringEntity entity = new StringEntity("[" + userId + "]");
  request.setEntity(entity);

  try {
    CloseableHttpResponse response = client.execute(request);
    System.out.println(response.getStatusLine());
  } catch (IOException e) {
    e.printStackTrace();
  }
}

HTTP/1.1 204 No Content

Die Überprüfung in der OneLogin Webseite ergibt, dass der User aus der Rolle entfernt wurde.

Interessant ist an dem Code, dass die Klasse HttpDelete des Apache HttpClients keinen Content im Body vorsieht.

Um trotzdem ein DELETE mit Body absenden zu können, war der einfachste Weg, ein HttpPost zu nehmen und dessen Methode zu überschreiben:

HttpPost request = new HttpPost(resourceURL) {
  @Override
  public String getMethod() {
    return "DELETE";
  }
};
[...]
request.setEntity(entity);

Delete User

Doku: Delete User - OneLogin Developers

private void deleteUser(Integer userId) throws Exception {
  String resourceURL = String.format("https://%%s.onelogin.com/api/2/users/%%d", ONELOGIN_SUBDOMAIN, userId);

  CloseableHttpClient client = HttpClientBuilder.create().build();

  HttpDelete request = new HttpDelete(resourceURL);
  request.setHeader("Authorization", "bearer " + getAccessToken());
  request.addHeader("Content-Type", "application/json");

  try {
    CloseableHttpResponse response = client.execute(request);
    System.out.println(response.getStatusLine());
  } catch (IOException e) {
    e.printStackTrace();
  }
}

HTTP/1.1 204 No Content

Damit ist Happy Gilmore Geschichte und auch in der Überprüfung auf der OneLogin Webseite nicht mehr zu finden.

GitHub

Die Dateien zu diesem Post sind im OneLogin-GitHub-Projekt unter version5 zu finden.

Leave a Reply

Your email address will not be published. Required fields are marked *