Anwender

Administratoren

Dienstleister

Partner

Einleitung

optiGov verwendet OAuth2.0 mit PKCE als Framework zur Authentifizierung von Benutzern.

Dabei wird zunächst kein Unterschied zwischen Mitarbeitern, Administratoren, DMS-Nutzern, Bürgern, o.Ä. getroffen.

Nach einer erfolgreichen Authentifizierung wird ein Token-Paar ausgestellt, welches aus einem kurzlebigen Access-Token und einem langlebigen Refresh-Token besteht. Das Access-Token ist an die in dem Token enthaltenen Scopes gebunden, welche bei der Authorisierung angefragt werden und durch den Nutzer erlaubt werden können.

OAuth2.0-Client einrichten

Um eine Authentifizierung eines Nutzers gegen optiGov durchführen zu können, ist es notwendig dies im Kontext eines “OAuth2.0 Client” zu tun. Dieser Client muss in der jeweiligen optiGov-Installation angelegt und eingerichtet werden. Dies muss durch einen Administrator dieser Installation geschehen, welcher folgende Informationen benötigt: - Name der authentifizierenden Anwendung - Return-URL(s) auf welche nach Authorisierung oder bei Abbruch weitergeleitet werden darf

Referenzimplementation

Inhalt dieser Seite ist eine Referenzimplementation, welche einen beispielhaften PKCE-Flow gegen die optiGov OAuth2.0 Schnittstelle implementiert.

Aufruf der Authentifizierung / Authorisierung

Als erster Schritt ist eine Authentifizierung und darauf aufbauende Authorisierung des Nutzers notwendig. Diese geschieht auf der Seite von optiGov, welche durch eine speziell zusammengesetzte URL aufgerufen wird.

// generate stateconst 
state = Str.random(40)
Store.store({key: "oauth-state", value: state})

// generate code verifier
const codeVerifier = Str.random(128)
Store.store({key: "oauth-code-verifier", value: codeVerifier})

// create code challenge
const codeChallenge = Base64.encode(await SHA256.hash(codeVerifier))

// create redirect url
const redirectUrl = "https://meine-redirect-url.dd"

// set url in body
this.url = window.config.oauth.endpoints.authorize 
	+  "?client_id=" + MEINE_CLIENT_ID 
	+  "&redirect_uri=" + encodeURIComponent(redirectUrl) 
	+  "&response_type=code" 
	+  "&scope=" + encodeURIComponent("LISTE_ALLER_SCOPES") 
	+  "&state=" + state 
	+  "&code_challenge=" + codeChallenge 
	+  "&code_challenge_method=S256"

// redirect to url
await window.location.href = this.url

Hinweis: optiGov verwendet OAuth2.0 für verschiedene weitere Authentifizierungskomponenten. Über das Parameter component können diese angesprochen werden. Standardmäßig wird die optiGov-Komponente verwendet. Um die Komponente für das Bürgerkonto zu verwenden kann beispielsweise wie folgt das Parameter in der URL ergänzt werden:

+ "&component=buergerkonto"

Erhalt eines Token-Paars

Nach erfolgreicher Authentifizierung und Authorisierung durch den Nutzer gelangt dieser auf die o.g. (und ebenfalls im OAuth2.0 Client hinterlegten) Redirect-URL. Auf dieser Seite kann nun der State verglichen, Auth-Code ausgelesen und gegen ein Token-Paar eingetauscht werden.

// get code from query
const code = this.$route.query.code

// get state from query
const state = this.$route.query.state

// check if state is equal the stored state
if (state !== Store.load({key: "oauth-state"})) {
    throw Error("Corrupt state detected")
}

// load code verifier
const codeVerifier = Store.load({key: "oauth-code-verifier"})

// create redirect url
const redirectUrl = location.protocol + "//" + window.location.host + router.resolve("/login/redirect").href

// get tokens by oauth code
const response = await axios.post(
	window.config.oauth.endpoints.token, 
	{    
		grant_type: 'authorization_code',    
		client_id: MEINE_CLIENT_ID,    
		redirect_uri: redirectUrl,    
		code_verifier: codeVerifier,    
		code: code
	}
)

// login user
await User.logIn({
	access_token: response.data.access_token,    
	refresh_token: response.data.refresh_token,
})

// destroy state and verifier in local storage
Store.destroy({key: "oauth-state"})
Store.destroy({key: "oauth-code-verifier"})

// redirect to dashboard
await window.location.href = "https://mein-dashboard.dd"

• Einleitung
• OAuth2.0-Client einrichten
• Referenzimplementation
• Aufruf der Authentifizierung / Authorisierung
• Erhalt eines Token-Paars