include::{mod-loc}shared/all-attributes.adoc[]

[id="managing-registry-artifacts-maven_{context}"]
= Managing {registry} content using the Maven plug-in

[role="_abstract"]
When developing client applications, you can use the {registry} Maven plug-in to manage schema and API artifacts stored in {registry}:

* xref:adding-artifacts-using-maven-plugin_{context}[]
* xref:downloading-artifacts-using-maven-plugin_{context}[]
* xref:testing-artifacts-using-maven-plugin_{context}[]
* xref:adding-artifact-references-manually-using-maven-plugin_{context}[]
* xref:adding-artifact-references-automatically-using-maven-plugin_{context}[]
* xref:configuring-tls-maven-plugin_{context}[]

.Prerequisites
* {registry} is installed and running in your environment.
* Apache Maven is installed and configured in your environment.

//INCLUDES


// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/as_installing-the-registry.adoc

[id="adding-artifacts-using-maven-plugin_{context}"]
== Adding schema and API artifacts using the Maven plug-in

[role="_abstract"]
The most common use case for the Maven plug-in is adding artifacts during a build of your client application. You can accomplish this by using the `register` execution goal.

.Prerequisites
* You have created a Maven project for your client application. For more details, see the https://maven.apache.org/index.html[Apache Maven documentation].

.Procedure
. Update your Maven `pom.xml` file to use the `apicurio-registry-maven-plugin` to register an artifact. The following example shows registering Apache Avro and GraphQL schemas:
+
[source,xml]
----
<plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
      <execution>
        <phase>generate-sources</phase>
        <goals>
            <goal>register</goal>  <1>
        </goals>
        <configuration>
            <registryUrl>MY-REGISTRY-URL/apis/registry/v3</registryUrl> <2>
            <authServerUrl>MY-AUTH-SERVER</authServerUrl>
            <clientId>MY-CLIENT-ID</clientId>
            <clientSecret>MY-CLIENT-SECRET</clientSecret> <3>
            <clientScope>MY-CLIENT-SCOPE</clientScope>
            <artifacts>
                <artifact>
                    <groupId>TestGroup</groupId> <4>
                    <artifactId>FullNameRecord</artifactId>
                    <file>${project.basedir}/src/main/resources/schemas/record.avsc</file>
                    <ifExists>FAIL</ifExists>
                </artifact>
                <artifact>
                    <groupId>TestGroup</groupId>
                    <artifactId>ExampleAPI</artifactId> <5>
                    <artifactType>GRAPHQL</artifactType>
                    <file>${project.basedir}/src/main/resources/apis/example.graphql</file>
                    <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                    <canonicalize>true</canonicalize>
                </artifact>
            </artifacts>
        </configuration>
    </execution>
  </executions>
 </plugin>
----
+
<1> Specify `register` as the execution goal to upload the schema artifact to {registry}.
<2> Specify the {registry} URL with the `../apis/registry/v3` endpoint.
<3> If authentication is required, you can specify your authentication server and client credentials.
<4> Specify the {registry} artifact group ID. You can specify the `default` group if you do not want to use a unique group ID.
<5> You can register multiple artifacts using the specified group ID, artifact ID, and location.

. Build your Maven project, for example, by using the `mvn package` command.

You can also run the `register` goal directly from the command line without a Maven project by passing the artifact configuration as system properties. Use the same field names that you would use in the Maven plug-in configuration:

[source,shell]
----
mvn io.apicurio:apicurio-registry-maven-plugin:${apicurio.version}:register \
  -Dapicurio.url=MY-REGISTRY-URL/apis/registry/v3 \
  -Dartifacts.groupId=TestGroup \
  -Dartifacts.artifactId=FullNameRecord \
  -Dartifacts.artifactType=AVRO \
  -Dartifacts.file=./src/main/resources/schemas/record.avsc \
  -Dartifacts.ifExists=FAIL
----

Use `artifacts.<field>` when registering a single artifact, or `artifacts.<index>.<field>` such as `artifacts.0.groupId` and `artifacts.1.groupId` when registering multiple artifacts.

For OpenAPI and AsyncAPI artifacts, you can set `versionStrategy` to `API_INFO_VERSION` to derive the version from the `info.version` field in the API document when `version` is not explicitly configured.

* If the derived version ends with `-SNAPSHOT`, the Maven plug-in strips the suffix before registration and registers the version as a draft.
* When the API document later uses the same version without the `-SNAPSHOT` suffix, the Maven plug-in updates the existing draft content and promotes that version to `ENABLED`.
* For other artifact types, `API_INFO_VERSION` is ignored.

To update draft content or promote a draft created in this way, artifact version mutability must be enabled on the server. For more details, see xref:assembly-deploying-registry-operator.adoc#configuring-registry-operator_{context}[Enabling artifact version mutability].

For list properties, use an additional numeric index. The following formats are supported:

* `artifacts.<index>.references.<index>.<field>`
* `artifacts.<index>.existingReferences.<index>.<field>`
* `artifacts.<index>.protoPaths.<index>`

When registering a single artifact, you can omit the artifact index and use `artifacts.references.0.name`, `artifacts.existingReferences.0.resourceName`, or `artifacts.protoPaths.0`.

[source,shell]
----
mvn io.apicurio:apicurio-registry-maven-plugin:${apicurio.version}:register \
  -Dapicurio.url=MY-REGISTRY-URL/apis/registry/v3 \
  -Dartifacts.0.groupId=TestGroup \
  -Dartifacts.0.artifactId=ExampleAPI \
  -Dartifacts.0.artifactType=ASYNCAPI \
  -Dartifacts.0.file=./src/main/resources/apis/example.yaml \
  -Dartifacts.0.references.0.name=SharedRecord \
  -Dartifacts.0.existingReferences.0.resourceName=./avro/shared.avsc \
  -Dartifacts.0.existingReferences.0.groupId=TestGroup \
  -Dartifacts.0.existingReferences.0.artifactId=shared-avro \
  -Dartifacts.0.existingReferences.0.version=1 \
  -Dartifacts.0.protoPaths.0=./src/main/proto \
  -Dartifacts.0.protoPaths.1=./src/main/proto/common
----

The following example derives the artifact version from an AsyncAPI or OpenAPI document:

[source,shell]
----
mvn io.apicurio:apicurio-registry-maven-plugin:${apicurio.version}:register \
  -Dapicurio.url=MY-REGISTRY-URL/apis/registry/v3 \
  -Dartifacts.groupId=TestGroup \
  -Dartifacts.artifactId=ExampleAPI \
  -Dartifacts.artifactType=ASYNCAPI \
  -Dartifacts.file=./src/main/resources/apis/example.yaml \
  -Dartifacts.versionStrategy=API_INFO_VERSION
----

[role="_additional-resources"]
.Additional resources
 * For more details on using Apache Maven, see the https://maven.apache.org/index.html[Apache Maven documentation].
 * For open source examples of using the {registry} Maven plug-in, see the link:https://github.com/Apicurio/apicurio-registry/tree/main/examples[Apicurio Registry demonstration examples].



// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/as_installing-the-registry.adoc

[id="downloading-artifacts-using-maven-plugin_{context}"]
== Downloading schema and API artifacts using the Maven plug-in

[role="_abstract"]
You can use the Maven plug-in to download artifacts from {registry}. This is often useful, for example, when generating code from a registered schema.

.Prerequisites
* You have created a Maven project for your client application. For more details, see the https://maven.apache.org/index.html[Apache Maven documentation].

.Procedure
. Update your Maven `pom.xml` file to use the `apicurio-registry-maven-plugin` to download an artifact. The following example shows downloading Apache Avro and GraphQL schemas.
+
[source,xml]
----
<plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>download</goal> <1>
      </goals>
      <configuration>
          <registryUrl>MY-REGISTRY-URL/apis/registry/v3</registryUrl> <2>
          <authServerUrl>MY-AUTH-SERVER</authServerUrl>
          <clientId>MY-CLIENT-ID</clientId>
          <clientSecret>MY-CLIENT-SECRET</clientSecret> <3>
          <clientScope>MY-CLIENT-SCOPE</clientScope>
          <artifacts>
              <artifact>
                  <groupId>TestGroup</groupId> <4>
                  <artifactId>FullNameRecord</artifactId> <5>
                  <file>${project.build.directory}/classes/record.avsc</file>
                  <overwrite>true</overwrite>
              </artifact>
              <artifact>
                  <groupId>TestGroup</groupId>
                  <artifactId>ExampleAPI</artifactId>
                  <version>1</version>
                  <file>${project.build.directory}/classes/example.graphql</file>
                  <overwrite>true</overwrite>
              </artifact>
          </artifacts>
      </configuration>
    </execution>
  </executions>
</plugin>
----
+
<1> Specify `download` as the execution goal.
<2> Specify the {registry} URL with the `../apis/registry/v3` endpoint.
<3> If authentication is required, you can specify your authentication server and client credentials.
<4> Specify the {registry} artifact group ID. You can specify the `default` group if you do not want to use a unique group.
<5> You can download multiple artifacts to a specified directory using the artifact ID.

. Build your Maven project, for example, by using the `mvn package` command.

[role="_additional-resources"]
.Additional resources
 * For more details on using Apache Maven, see the https://maven.apache.org/index.html[Apache Maven documentation].
 * For open source examples of using the {registry} Maven plug-in, see the link:https://github.com/Apicurio/apicurio-registry/tree/main/examples[Apicurio Registry demonstration examples].



// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/as_installing-the-registry.adoc

[id="testing-artifacts-using-maven-plugin_{context}"]
== Testing schema and API artifacts using the Maven plug-in

[role="_abstract"]
You might want to verify that an artifact can be registered without actually making any changes. This is often useful when rules are configured in {registry}. Testing the artifact results in a failure if the artifact content violates any of the configured rules.

NOTE: When testing artifacts using the Maven plug-in, even if the artifact passes the test, no content is added to {registry}.

.Prerequisites
* You have created a Maven project for your client application. For more details, see the https://maven.apache.org/index.html[Apache Maven documentation].


.Procedure
. Update your Maven `pom.xml` file to use the `apicurio-registry-maven-plugin` to test an artifact. The following example shows testing an Apache Avro schema:
+
[source,xml]
----
<plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
      <execution>
        <phase>generate-sources</phase>
        <goals>
            <goal>test-update</goal>  <1>
        </goals>
        <configuration>
            <registryUrl>MY-REGISTRY-URL/apis/registry/v3</registryUrl> <2>
            <authServerUrl>MY-AUTH-SERVER</authServerUrl>
            <clientId>MY-CLIENT-ID</clientId>
            <clientSecret>MY-CLIENT-SECRET</clientSecret> <3>
            <clientScope>MY-CLIENT-SCOPE</clientScope>
            <artifacts>
                <artifact>
                    <groupId>TestGroup</groupId> <4>
                    <artifactId>FullNameRecord</artifactId>
                    <file>${project.basedir}/src/main/resources/schemas/record.avsc</file> <5>
                </artifact>
            </artifacts>
        </configuration>
    </execution>
  </executions>
 </plugin>
----
+
<1> Specify `test-update` as the execution goal to test the schema artifact.
<2> Specify the {registry} URL with the `../apis/registry/v3` endpoint.
<3> If authentication is required, you can specify your authentication server and client credentials.
<4> Specify the {registry} artifact group ID. You can specify the `default` group if you do not want to use a unique group.
<5> You can test multiple artifacts from a specified directory using the artifact ID.

. Build your Maven project, for example, by using the `mvn package` command.

[role="_additional-resources"]
.Additional resources
 * For more details on using Apache Maven, see the https://maven.apache.org/index.html[Apache Maven documentation].
 * For open source examples of using the {registry} Maven plug-in, see the link:https://github.com/Apicurio/apicurio-registry/tree/main/examples[Apicurio Registry demonstration examples].



// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/assembly-managing-registry-artifacts-maven.adoc

[id="adding-artifact-references-manually-using-maven-plugin_{context}"]
== Adding artifact references manually using the {registry} Maven plug-in

[role="_abstract"]
Some {registry} artifact types can include _artifact references_ from one artifact file to another. You can create efficiencies by defining reusable schema or API artifacts, and then referencing them from multiple locations in artifact references.

The following artifact types support artifact references:

* Apache Avro
* Google Protobuf
* JSON Schema
* OpenAPI
* AsyncAPI

This section shows a simple example of using the {registry} Maven plug-in to manually register an artifact reference to a simple Avro schema artifact stored in {registry}. This example assumes that the following `Exchange` schema artifact has already been created in {registry}:

.Exchange schema
[source,json]
----
{
  "namespace": "com.kubetrade.schema.common",
  "type": "enum",
  "name": "Exchange",
  "symbols" : ["GEMINI"]
}
----

This example then creates a `TradeKey` schema artifact, which includes a reference to the nested `Exchange` schema artifact:

.TradeKey schema with nested reference to Exchange schema
[source,json]
----
{
  "namespace": "com.kubetrade.schema.trade",
  "type": "record",
  "name": "TradeKey",
  "fields": [
    {
      "name": "exchange",
      "type": "com.kubetrade.schema.common.Exchange"
    },
    {
      "name": "key",
      "type": "string"
    }
  ]
}
----

.Prerequisites
* You have created a Maven project for your client application. For more details, see the https://maven.apache.org/index.html[Apache Maven documentation].
* The referenced `Exchange` schema artifact is already created in {registry}.

.Procedure
. Update your Maven `pom.xml` file to use the `apicurio-registry-maven-plugin` to register the `TradeKey` schema, which includes a nested reference to the `Exchange` schema as follows:
+
[source,xml]
----
<plugin>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-maven-plugin</artifactId>
    <version>${apicurio-registry.version}</version>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <goals>
                <goal>register</goal> <1>
            </goals>
            <configuration>
                <registryUrl>MY-REGISTRY-URL/apis/registry/v3</registryUrl> <2>
                <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                <clientId>MY-CLIENT-ID</clientId>
                <clientSecret>MY-CLIENT-SECRET</clientSecret> <3>
                <clientScope>MY-CLIENT-SCOPE</clientScope>
                <artifacts>
                    <artifact>
                        <groupId>test-group</groupId> <4>
                        <artifactId>TradeKey</artifactId>
                        <version>2.0</version>
                        <artifactType>AVRO</artifactType>
                        <file>
                            ${project.basedir}/src/main/resources/schemas/TradeKey.avsc
                        </file>
                        <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                        <canonicalize>true</canonicalize>
                        <references>
                            <reference> <5>
                                <name>com.kubetrade.schema.common.Exchange</name>
                                <groupId>test-group</groupId>
                                <artifactId>Exchange</artifactId>
                                <version>2.0</version>
                                <artifactType>AVRO</artifactType>
                                <file>
                                    ${project.basedir}/src/main/resources/schemas/Exchange.avsc
                                </file>
                                <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                                <canonicalize>true</canonicalize>
                            </reference>
                        </references>
                    </artifact>
                </artifacts>
            </configuration>
        </execution>
    </executions>
</plugin>
----
+
<1> Specify `register` as the execution goal to upload the schema artifacts to {registry}.
<2> Specify the {registry} URL by using the `../apis/registry/v3` endpoint.
<3> If authentication is required, you can specify your authentication server and client credentials.
<4> Specify the {registry} artifact group ID. You can specify the `default` group if you do not want to use a unique group ID.
<5> Specify the {registry} artifact reference using its group ID, artifact ID, version, type, and location. You can register multiple artifact references in this way.

. Build your Maven project, for example, by using the `mvn package` command.

[role="_additional-resources"]
.Additional resources
 * For more details on using Apache Maven, see the https://maven.apache.org/index.html[Apache Maven documentation].
 * For an open source example of using the {registry} Maven plug-in to manually register an artifact reference, see the link:https://github.com/Apicurio/apicurio-registry/tree/main/examples/avro-maven-with-references[avro-maven-with-references demonstration example].
 * For more examples of artifact references, see the section on configuring each artifact type in {registry-client-serdes-config}.





// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/assembly-managing-registry-artifacts-maven.adoc

[id="adding-artifact-references-automatically-using-maven-plugin_{context}"]
== Adding artifact references automatically using the {registry} Maven plug-in

[role="_abstract"]
Some {registry} artifact types can include _artifact references_ from one artifact file to another. You can create efficiencies by defining reusable schema or API artifacts, and then referencing them from multiple locations in artifact references.

The following artifact types support artifact references:

* Apache Avro
* Google Protobuf
* JSON Schema
* OpenAPI
* AsyncAPI

You can specify a single artifact and configure the {registry} Maven plugin to automatically detect all references to artifacts located in the same directory, and to automatically register those references. This is a Technology Preview feature.

[IMPORTANT]
====
Technology Preview features are not supported with Red{nbsp}Hat production service level agreements (SLAs) and might not be functionally complete.
Red{nbsp}Hat does not recommend using them in production.
These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red{nbsp}Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope].
====

This section shows a simple example of using the Maven plug-in to register an Avro schema and automatically detect and register an artifact reference to a simple schema artifact. This example assumes that the parent `TradeKey` artifact and the nested `Exchange` schema artifact are both available in the same directory:

.TradeKey schema with nested reference to Exchange schema
[source,json]
----
{
  "namespace": "com.kubetrade.schema.trade",
  "type": "record",
  "name": "TradeKey",
  "fields": [
    {
      "name": "exchange",
      "type": "com.kubetrade.schema.common.Exchange"
    },
    {
      "name": "key",
      "type": "string"
    }
  ]
}
----

.Exchange schema
[source,json]
----
{
  "namespace": "com.kubetrade.schema.common",
  "type": "enum",
  "name": "Exchange",
  "symbols" : ["GEMINI"]
}
----

.Prerequisites
* You have created a Maven project for your client application. For more details, see the https://maven.apache.org/index.html[Apache Maven documentation].
* The `TradeKey` schema artifact and the nested `Exchange` schema artifact files are both located in the same directory.

.Procedure
. Update your Maven `pom.xml` file to use the `apicurio-registry-maven-plugin` to register the `TradeKey` schema, which includes a nested reference to the `Exchange` schema as follows:
+
[source,xml]
----
<plugin>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-maven-plugin</artifactId>
    <version>${apicurio-registry.version}</version>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <goals>
                <goal>register</goal> <1>
            </goals>
            <configuration>
                <registryUrl>MY-REGISTRY-URL/apis/registry/v3</registryUrl> <2>
                <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                <clientId>MY-CLIENT-ID</clientId>
                <clientSecret>MY-CLIENT-SECRET</clientSecret> <3>
                <clientScope>MY-CLIENT-SCOPE</clientScope>
                <artifacts>
                    <artifact>
                        <groupId>test-group</groupId> <4>
                        <artifactId>TradeKey</artifactId>
                        <version>2.0</version>
                        <artifactType>AVRO</artifactType>
                        <file>
                            ${project.basedir}/src/main/resources/schemas/TradeKey.avsc <5>
                        </file>
                        <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                        <canonicalize>true</canonicalize>
                        <autoRefs>true</autoRefs> <6>
                    </artifact>
                </artifacts>
            </configuration>
        </execution>
    </executions>
</plugin>
----
+
<1> Specify `register` as the execution goal to upload the schema artifacts to {registry}.
<2> Specify the {registry} URL by using the `../apis/registry/v3` endpoint.
<3> If authentication is required, you can specify your authentication server and client credentials.
<4> Specify the parent artifact group ID that contains the references. You can specify the `default` group if you do not want to use a unique group ID.
<5> Specify the location of the parent artifact file. All referenced artifacts must also be located in the same directory.
<6> Set the `<autoRefs>` option to true to automatically detect and register all references to artifacts in the same directory. You can register multiple artifact references in this way.

. Build your Maven project, for example, by using the `mvn package` command.

[role="_additional-resources"]
.Additional resources
 * For more details on using Apache Maven, see the https://maven.apache.org/index.html[Apache Maven documentation].
 * For an open source example of using the {registry} Maven plug-in to automatically register multiple artifact references, see the link:https://github.com/Apicurio/apicurio-registry/tree/main/examples/avro-maven-with-references-auto[avro-maven-with-references-auto demonstration example].
 * For more examples of artifact references, see the section on configuring each artifact type in {registry-client-serdes-config}.



[id="configuring-tls-maven-plugin_{context}"]
== Configuring TLS and authentication for the Maven plug-in

[role="_abstract"]
When connecting to a TLS-enabled {registry} instance, you can configure the Maven plug-in to use SSL/TLS for secure communication. The plug-in supports various trust store and key store formats, as well as multiple authentication methods.

=== TLS configuration options

The following table describes the TLS-related configuration options available in the Maven plug-in:

.Trust store configuration
[cols="1,3",options="header"]
|===
|Parameter
|Description

|`trustStorePath`
|Path to the trust store file containing the CA certificate(s) to trust. Supports JKS, PKCS12, and PEM formats. The format is auto-detected from the file extension (`.jks`, `.p12`/`.pfx`, `.pem`/`.crt`/`.cer`) unless explicitly specified.

|`trustStorePassword`
|Password for the trust store. Required for JKS and PKCS12 formats.

|`trustStoreType`
|Explicit trust store type: `JKS`, `PKCS12`, or `PEM`. If not specified, the type is auto-detected from the file extension.
|===

.Key store configuration for mutual TLS (mTLS)
[cols="1,3",options="header"]
|===
|Parameter
|Description

|`keyStorePath`
|Path to the key store file containing the client certificate for mTLS authentication. Supports JKS, PKCS12, and PEM formats.

|`keyStorePassword`
|Password for the key store. Required for JKS and PKCS12 formats.

|`keyStoreType`
|Explicit key store type: `JKS`, `PKCS12`, or `PEM`. If not specified, the type is auto-detected from the file extension.

|`keyStorePemKeyPath`
|Path to the PEM private key file. Required when using PEM format for mTLS, where `keyStorePath` points to the certificate file.
|===

.Additional SSL options
[cols="1,1,3",options="header"]
|===
|Parameter
|Default
|Description

|`trustAll`
|`false`
|If set to `true`, trust all SSL/TLS certificates without validation. *WARNING:* This should only be used for development or testing purposes.

|`verifyHostname`
|`true`
|If set to `false`, disable hostname verification in SSL/TLS connections. *WARNING:* Disabling this reduces security and should only be used for development or testing.
|===

=== Example: TLS with PKCS12 trust store

The following example shows how to configure the Maven plug-in to connect to a TLS-enabled {registry} using a PKCS12 trust store:

[source,xml]
----
<plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>register</goal>
      </goals>
      <configuration>
          <registryUrl>https://registry.example.com:8443/apis/registry/v3</registryUrl> <1>
          <trustStorePath>${project.basedir}/certs/truststore.p12</trustStorePath> <2>
          <trustStorePassword>${env.TRUSTSTORE_PASSWORD}</trustStorePassword> <3>
          <artifacts>
              <artifact>
                  <groupId>default</groupId>
                  <artifactId>MySchema</artifactId>
                  <file>${project.basedir}/src/main/resources/schemas/schema.avsc</file>
              </artifact>
          </artifacts>
      </configuration>
    </execution>
  </executions>
</plugin>
----
<1> Use `https://` for the registry URL when connecting with TLS.
<2> Specify the path to your PKCS12 trust store containing the CA certificate(s).
<3> Use environment variables for passwords to avoid storing secrets in your `pom.xml`.

=== Example: TLS with basic authentication

The following example shows how to combine TLS with basic authentication:

[source,xml]
----
<plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>register</goal>
      </goals>
      <configuration>
          <registryUrl>https://registry.example.com:8443/apis/registry/v3</registryUrl>
          <trustStorePath>${project.basedir}/certs/truststore.p12</trustStorePath>
          <trustStorePassword>${env.TRUSTSTORE_PASSWORD}</trustStorePassword>
          <username>${env.REGISTRY_USERNAME}</username> <1>
          <password>${env.REGISTRY_PASSWORD}</password>
          <artifacts>
              <artifact>
                  <groupId>default</groupId>
                  <artifactId>MySchema</artifactId>
                  <file>${project.basedir}/src/main/resources/schemas/schema.avsc</file>
              </artifact>
          </artifacts>
      </configuration>
    </execution>
  </executions>
</plugin>
----
<1> Combine TLS configuration with basic authentication credentials.

=== Example: TLS with OAuth2 authentication

The following example shows how to configure TLS with OAuth2/OIDC client credentials authentication:

[source,xml]
----
<plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>register</goal>
      </goals>
      <configuration>
          <registryUrl>https://registry.example.com:8443/apis/registry/v3</registryUrl>
          <trustStorePath>${project.basedir}/certs/truststore.p12</trustStorePath>
          <trustStorePassword>${env.TRUSTSTORE_PASSWORD}</trustStorePassword>
          <authServerUrl>https://keycloak.example.com/realms/registry/protocol/openid-connect/token</authServerUrl> <1>
          <clientId>${env.CLIENT_ID}</clientId>
          <clientSecret>${env.CLIENT_SECRET}</clientSecret>
          <clientScope>openid</clientScope>
          <artifacts>
              <artifact>
                  <groupId>default</groupId>
                  <artifactId>MySchema</artifactId>
                  <file>${project.basedir}/src/main/resources/schemas/schema.avsc</file>
              </artifact>
          </artifacts>
      </configuration>
    </execution>
  </executions>
</plugin>
----
<1> Specify the OAuth2/OIDC token endpoint URL for authentication.

=== Example: Mutual TLS (mTLS)

The following example shows how to configure mutual TLS where both the client and server authenticate each other using certificates:

[source,xml]
----
<plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>register</goal>
      </goals>
      <configuration>
          <registryUrl>https://registry.example.com:8443/apis/registry/v3</registryUrl>
          <trustStorePath>${project.basedir}/certs/truststore.p12</trustStorePath> <1>
          <trustStorePassword>${env.TRUSTSTORE_PASSWORD}</trustStorePassword>
          <keyStorePath>${project.basedir}/certs/client-keystore.p12</keyStorePath> <2>
          <keyStorePassword>${env.KEYSTORE_PASSWORD}</keyStorePassword>
          <artifacts>
              <artifact>
                  <groupId>default</groupId>
                  <artifactId>MySchema</artifactId>
                  <file>${project.basedir}/src/main/resources/schemas/schema.avsc</file>
              </artifact>
          </artifacts>
      </configuration>
    </execution>
  </executions>
</plugin>
----
<1> Trust store to verify the server's certificate.
<2> Key store containing the client certificate for authentication.

=== Example: TLS with PEM certificates

The following example shows how to use PEM-formatted certificates:

[source,xml]
----
<plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>register</goal>
      </goals>
      <configuration>
          <registryUrl>https://registry.example.com:8443/apis/registry/v3</registryUrl>
          <trustStorePath>${project.basedir}/certs/ca-cert.pem</trustStorePath> <1>
          <trustStoreType>PEM</trustStoreType>
          <artifacts>
              <artifact>
                  <groupId>default</groupId>
                  <artifactId>MySchema</artifactId>
                  <file>${project.basedir}/src/main/resources/schemas/schema.avsc</file>
              </artifact>
          </artifacts>
      </configuration>
    </execution>
  </executions>
</plugin>
----
<1> PEM certificate files do not require a password.

=== Example: mTLS with PEM certificates

The following example shows mTLS configuration using PEM-formatted certificate and key files:

[source,xml]
----
<plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>register</goal>
      </goals>
      <configuration>
          <registryUrl>https://registry.example.com:8443/apis/registry/v3</registryUrl>
          <trustStorePath>${project.basedir}/certs/ca-cert.pem</trustStorePath>
          <trustStoreType>PEM</trustStoreType>
          <keyStorePath>${project.basedir}/certs/client-cert.pem</keyStorePath> <1>
          <keyStorePemKeyPath>${project.basedir}/certs/client-key.pem</keyStorePemKeyPath> <2>
          <keyStoreType>PEM</keyStoreType>
          <artifacts>
              <artifact>
                  <groupId>default</groupId>
                  <artifactId>MySchema</artifactId>
                  <file>${project.basedir}/src/main/resources/schemas/schema.avsc</file>
              </artifact>
          </artifacts>
      </configuration>
    </execution>
  </executions>
</plugin>
----
<1> Path to the client certificate PEM file.
<2> Path to the client private key PEM file. Required when using PEM format for mTLS.

[role="_additional-resources"]
.Additional resources
 * For more details on using Apache Maven, see the https://maven.apache.org/index.html[Apache Maven documentation].
 * For a complete example with multiple TLS and authentication configurations, see the link:https://github.com/Apicurio/apicurio-registry/tree/main/examples/maven-plugin-tls-credentials[maven-plugin-tls-credentials demonstration example].
 * For a Kubernetes mTLS setup example, see the link:https://github.com/Apicurio/apicurio-registry/tree/main/examples/mtls-minikube[mTLS Minikube demonstration example].


