You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/src/docs/asciidoc/guides/how-to-jpa.adoc
+32-22
Original file line number
Diff line number
Diff line change
@@ -1,27 +1,30 @@
1
1
[[how-to-jpa]]
2
2
= How-to: Implement core services with JPA
3
-
:toc: left
4
-
:toclevels: 3
5
3
:index-link: ../how-to.html
6
4
:docs-dir: ..
7
5
:examples-dir: ../examples
8
6
9
7
[[jpa-getting-started]]
10
8
== Getting Started
11
9
12
-
In this guide, we will demonstrate how to implement the xref:{docs-dir}/core-model-components.adoc#core-model-components[core services] of xref:{docs-dir}/index.adoc#top[Spring Authorization Server] with JPA. The purpose of this guide is to provide a starting point for implementing these services yourself, with the intention that you will make modifications as necessary to suit your needs.
10
+
This guide shows how to implement the xref:{docs-dir}/core-model-components.adoc#core-model-components[core services] of xref:{docs-dir}/index.adoc#top[Spring Authorization Server] with JPA.
11
+
The purpose of this guide is to provide a starting point for implementing these services yourself, with the intention that you can make modifications to suit your needs.
13
12
14
13
[[jpa-define-data-model]]
15
14
== Define the data model
16
15
17
-
This guide seeks to provide a starting point for the data model and uses the simplest possible structure and data types. To come up with the initial schema, we begin by reviewing the xref:{docs-dir}/core-model-components.adoc#core-model-components[domain objects] used by the core services. Please note:
16
+
This guide provides a starting point for the data model and uses the simplest possible structure and data types.
17
+
To come up with the initial schema, we begin by reviewing the xref:{docs-dir}/core-model-components.adoc#core-model-components[domain objects] used by the core services.
18
18
19
-
NOTE: Except for token, state, metadata, settings and claims values, we will use the JPA default column length of 255 for all columns. In reality, the length and even type of columns you use may need to be customized. Your mileage may vary and you are encouraged to experiment and test before deploying to production.
19
+
NOTE: Except for token, state, metadata, settings, and claims values, we use the JPA default column length of 255 for all columns.
20
+
In reality, the length and even type of columns you use may need to be customized.
21
+
You are encouraged to experiment and test before deploying to production.
20
22
21
23
[[jpa-client-schema]]
22
24
=== Client Schema
23
25
24
-
The xref:{docs-dir}/core-model-components.adoc#registered-client[`RegisteredClient`] domain object contains a few multi-valued fields and some settings fields that require storing arbitrary key/value data. The following is an example that we will use to create a JPA entity.
26
+
The xref:{docs-dir}/core-model-components.adoc#registered-client[`RegisteredClient`] domain object contains a few multi-valued fields and some settings fields that require storing arbitrary key/value data.
The xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object is more complex, and contains several multi-valued fields as well as numerous arbitrarily long token values, metadata, settings and claims values. The built-in JDBC implementation utilizes a flattened structure that prefers performance over normalization, which we adopt here as well.
38
+
The xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object is more complex and contains several multi-valued fields as well as numerous arbitrarily long token values, metadata, settings and claims values.
39
+
The built-in JDBC implementation utilizes a flattened structure that prefers performance over normalization, which we adopt here as well.
36
40
37
-
CAUTION: It has been difficult to find a flattened database schema that works well in all cases and with all database vendors. You may need to normalize or heavily alter the following schema for your needs.
41
+
CAUTION: It has been difficult to find a flattened database schema that works well in all cases and with all database vendors.
42
+
You may need to normalize or heavily alter the following schema for your needs.
38
43
39
-
The following is an example that we will use to create a JPA entity.
44
+
The following listing shows the `authorization` schema.
The xref:{docs-dir}/core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object is the simplest to model, and only contains a single multi-valued field in addition to a composite key. The following is an example that we will use to create a JPA entity.
55
+
The xref:{docs-dir}/core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object is the simplest to model and contains only a single multi-valued field in addition to a composite key.
56
+
The following listing shows the `authorizationConsent` schema.
The preceding schema examples provide a reference for the structure of the entities we need to create.
62
68
63
-
NOTE: The following entities are minimally annotated and are just examples. They allow the schema to be created dynamically and therefore do not require the above sql scripts to be executed manually.
69
+
NOTE: The following entities are minimally annotated and are just examples.
70
+
They allow the schema to be created dynamically and therefore do not require the above sql scripts to be executed manually.
64
71
65
72
[[jpa-client-entity]]
66
73
=== Client Entity
67
74
68
-
The following is an example of the `Client` entity which is used to persist information mapped from the xref:{docs-dir}/core-model-components.adoc#registered-client[`RegisteredClient`] domain object.
75
+
The following listing shows the `Client` entity, which is used to persist information mapped from the xref:{docs-dir}/core-model-components.adoc#registered-client[`RegisteredClient`] domain object.
The following is an example of the `Authorization` entity which is used to persist information mapped from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object.
86
+
The following listing shows the `Authorization` entity, which is used to persist information mapped from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object.
The following is an example of the `AuthorizationConsent` entity which is used to persist information mapped from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object.
97
+
The following listing shows the `AuthorizationConsent` entity, which is used to persist information mapped from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object.
91
98
92
99
.Authorization Consent Entity
93
100
[source,java]
@@ -103,7 +110,7 @@ By closely examining the interfaces of each core service and reviewing the `Jdbc
103
110
[[jpa-client-repository]]
104
111
=== Client Repository
105
112
106
-
The following is an example of the `ClientRepository` capable of finding a <<jpa-client-entity,`Client`>> by the `id` and `clientId` fields.
113
+
The following listing shows the `ClientRepository`, which is able to find a <<jpa-client-entity,`Client`>> by the `id` and `clientId` fields.
The following is an example of the `AuthorizationRepository` capable of finding an <<jpa-authorization-entity,`Authorization`>> by the `id` field as well as the `state`, `authorizationCodeValue`, `accessTokenValue` and `refreshTokenValue` token fields. It also allows querying a combination of token fields.
124
+
The following listing shows the `AuthorizationRepository`, which is able to find an <<jpa-authorization-entity,`Authorization`>> by the `id` field as well as the `state`, `authorizationCodeValue`, `accessTokenValue` and `refreshTokenValue` token fields.
125
+
It also allows querying a combination of token fields.
The following is an example of the `AuthorizationConsentRepository` capable of finding and deleting an <<jpa-authorization-consent-entity,`AuthorizationConsent`>> by the `registeredClientId` and `principalName` fields, which form a composite primary key.
136
+
The following listing shows the `AuthorizationConsentRepository`, which is able to find and delete an <<jpa-authorization-consent-entity,`AuthorizationConsent`>> by the `registeredClientId` and `principalName` fields that form a composite primary key.
With the above <<jpa-create-jpa-entities,entities>> and <<jpa-create-spring-data-repositories,repositories>>, we can begin implementing the core services. By reviewing the `Jdbc` implementations, we can derive a minimal set of internal utilities for converting to/from string values for enumerations and reading/writing JSON data for attributes, settings, metadata and claims fields.
147
+
With the above <<jpa-create-jpa-entities,entities>> and <<jpa-create-spring-data-repositories,repositories>>, we can begin implementing the core services.
148
+
By reviewing the `Jdbc` implementations, we can derive a minimal set of internal utilities for converting to and from string values for enumerations and reading and writing JSON data for attributes, settings, metadata and claims fields.
140
149
141
-
CAUTION: Keep in mind that writing JSON data to text columns with a fixed length has proven problematic with the `Jdbc` implementations. While these examples continue to do so, you may need to split these fields out into a separate table or data store that supports arbitrarily long data values.
150
+
CAUTION: Keep in mind that writing JSON data to text columns with a fixed length has proven problematic with the `Jdbc` implementations.
151
+
While these examples continue to do so, you may need to split these fields out into a separate table or data store that supports arbitrarily long data values.
142
152
143
153
[[jpa-registered-client-repository]]
144
154
=== Registered Client Repository
145
155
146
-
The following is an example of the `JpaRegisteredClientRepository` which uses a <<jpa-client-repository,`ClientRepository`>> for persisting a <<jpa-client-entity,`Client`>>, and maps to/from the xref:{docs-dir}/core-model-components.adoc#registered-client[`RegisteredClient`] domain object.
156
+
The following listing shows the `JpaRegisteredClientRepository`, which uses a <<jpa-client-repository,`ClientRepository`>> for persisting a <<jpa-client-entity,`Client`>> and maps to and from the xref:{docs-dir}/core-model-components.adoc#registered-client[`RegisteredClient`] domain object.
The following is an example of the `JpaOAuth2AuthorizationService` which uses an <<jpa-authorization-repository,`AuthorizationRepository`>> for persisting an <<jpa-authorization-entity,`Authorization`>>, and maps to/from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object.
167
+
The following listing shows the `JpaOAuth2AuthorizationService`, which uses an <<jpa-authorization-repository,`AuthorizationRepository`>> for persisting an <<jpa-authorization-entity,`Authorization`>> and maps to and from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`] domain object.
The following is an example of the `JpaOAuth2AuthorizationConsentService` which uses an <<jpa-authorization-consent-repository,`AuthorizationConsentRepository`>> for persisting an <<jpa-authorization-consent-entity,`AuthorizationConsent`>>, and maps to/from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object.
178
+
The following listing shows the `JpaOAuth2AuthorizationConsentService`, which uses an <<jpa-authorization-consent-repository,`AuthorizationConsentRepository`>> for persisting an <<jpa-authorization-consent-entity,`AuthorizationConsent`>> and maps to and from the xref:{docs-dir}/core-model-components.adoc#oauth2-authorization-consent[`OAuth2AuthorizationConsent`] domain object.
0 commit comments