Vooraf
De meeste backend-extensies voegen iets toe: een service die je zelf aanroept, een geplande taak, een eigen endpoint. Bij het overschrijven van platformgedrag werkt het omgekeerd. Het platform roept jouw code aan, in plaats van zijn eigen standaardversie. Je vervangt dus een stuk standaardgedrag. In de termen van Wat zijn extensies & customizaties? is dat een customizatie.
Dat kan alleen voor klassen die het platform daarvoor voorziet. Zo'n klasse heeft methodes die bedoeld zijn om te overschrijven, en het platform gebruikt automatisch jouw versie zodra die als Spring bean in de applicatie aanwezig is.
Het voorbeeld op deze pagina is het gebruikersprofiel. Wanneer een gebruiker aanmeldt, bouwt het platform een profiel op uit de gegevens (claims) die de identity provider via OpenID meestuurt. Standaard leest het platform daarbij een vaste set claims. Gebruikt jouw identity provider andere claims, bijvoorbeeld voor de rollen van de gebruiker, dan overschrijf je het profiel.
Stap 1: maak een subklasse van de platformklasse
Je maakt een klasse die de platformklasse Profile uitbreidt. Daarin lees je de extra claims in en overschrijf je de methodes waarvan je het gedrag wilt wijzigen:
@Data
@EqualsAndHashCode(callSuper = true)
@ToString(callSuper = true)
@JsonIgnoreProperties(ignoreUnknown = true)
public class MijnappProfile extends Profile {
@JsonProperty("employee_id")
private String employeeId;
@JsonProperty("groups")
private List<String> groups;
@Override
public List<String> getParsedRoles() {
return groups;
}
@Override
public String getSub() {
if (employeeId != null && !employeeId.isBlank()) {
return employeeId;
}
return super.getSub();
}
}
In dit voorbeeld:
-
getParsedRoles()haalt de rollen van de gebruiker uit de claimgroups. -
getSub()bepaalt de identiteit van de gebruiker. Hier is dat de claimemployee_id, met de standaardidentiteit als terugval. -
@JsonIgnoreProperties(ignoreUnknown = true)zorgt ervoor dat claims die je niet gebruikt, geen fout veroorzaken.
Stap 2: registreer je versie bij het platform
Het platform moet weten dat het jouw profiel moet gebruiken. Daarvoor maak je een subklasse van de platformklasse ProfileMapper, die naar jouw profielklasse verwijst, en registreer je ze als Spring bean:
@Component
public class MijnappProfileMapper extends ProfileMapper<MijnappProfile> {
@Override
protected Class<MijnappProfile> clazz() {
return MijnappProfile.class;
}
}
Meer is er niet nodig: zodra de applicatie opstart met deze bean, bouwt het platform voortaan een MijnappProfile op in plaats van het standaardprofiel.
Applicaties bundelen deze klassen vaak in een eigen module, bijvoorbeeld openid, naast de module backend. Hoe je zo'n module in de applicatie opneemt, lees je op Opbouw van een Skryv applicatie.
Stap 3: test het gedrag
Schrijf een unittest voor elke methode die je overschrijft, zeker wanneer er terugvallogica in zit zoals in getSub(). Test minstens:
-
een profiel waarin alle claims aanwezig zijn
-
een profiel waarin de claim ontbreekt waarop je eerst terugvalt
-
een profiel met een lege lijst rollen
Waar je op moet letten
-
De identiteit die
getSub()teruggeeft, is de sleutel waarmee het platform een gebruiker herkent: bij toegewezen taken, de dossierbehandelaar en de historiek. Wijzig je achteraf welke claim je gebruikt, of begint de identity provider een claim anders te vullen, dan wordt dezelfde persoon een nieuwe gebruiker. Taken en dossiers verwijzen dan naar een identiteit die niet meer aanmeldt. Kies de identiteitsclaim daarom bij de start van een project, en wijzig ze nadien alleen met een migratie. -
De rollen die
getParsedRoles()teruggeeft, moeten exact overeenkomen met de rollen die in je applicatie gedefinieerd zijn. Een afwijkende schrijfwijze in de identity provider geeft geen foutmelding: de gebruiker meldt gewoon aan zonder de verwachte rechten. -
Wie platformgedrag overschrijft, neemt de verantwoordelijkheid over voor wat het origineel deed. Controleer bij elke platformupgrade in de release notes of de klasse die je overschrijft, gewijzigd is.
Resultaat
Het platform gebruikt jouw versie van de klasse. In het voorbeeld krijgen gebruikers hun identiteit en rollen uit de claims van jouw identity provider. Het overschrijven van onderdelen van de backoffice en de frontoffice lees je onder Frontend-customizaties.