Skip to content
This repository has been archived by the owner on Nov 8, 2024. It is now read-only.

Commit

Permalink
Update README.adoc
Browse files Browse the repository at this point in the history
  • Loading branch information
rwinch authored Nov 8, 2024
1 parent 66bf515 commit 64d74f9
Showing 1 changed file with 1 addition and 114 deletions.
115 changes: 1 addition & 114 deletions README.adoc
Original file line number Diff line number Diff line change
@@ -1,114 +1 @@
This is a sample application to experiment with passkeys and eventually be merged into Spring Security.

== Using in your own project

Clone the repository and then publish to your local file system.

[source,bash]
----
./gradlew publish
tree build/repo
build/repo
└── io
└── github
└── rwinch
└── webauthn
└── spring-security-webauthn
├── 0.0.1-SNAPSHOT
│   ├── maven-metadata.xml
│   ├── spring-security-webauthn-0.0.1-20240510.034131-1.jar
│   ├── spring-security-webauthn-0.0.1-20240510.034131-1.pom
│   ├── ...
├── ...
├── maven-metadata.xml
----


Then you can add it as a dependency:

.pom.xml
[source,xml]
----
<dependencies>
<dependency>
<groupId>io.github.rwinch.webauthn</groupId>
<artifactId>spring-security-webauthn</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
<!-- ... -->
</dependencies>
<repositories>
<repository>
<id>spring-webauthn</id>
<!-- replace with the path to the build/repo on your file system -->
<url>file:///home/rwinch/code/rwinch/spring-security-webauthn/main/build/repo/</url>
</repository>
<!-- ... -->
</repositories>
----


.build.gradle
[source,groovy]
----
dependencies {
implementation 'io.github.rwinch.webauthn:spring-security-webauthn:0.0.1-SNAPSHOT'
// ...
}
repositories {
maven {
// replace with the path to the build/repo on your file system
url = 'file:///home/rwinch/code/rwinch/spring-security-webauthn/main/build/repo/'
}
// ...
}
----

Alternatively, you can publish to your Maven local cache:

[source,bash]
----
./gradlew publishToMavenLocal
----

== https://example.localhost.example:8443

Many Authenticators do will not work unless https is used & some will not work with localhost.
This section discusses how to setup your workspace to use https://example.localhost:8443/ with a certificate that is signed by a trusted CA.

=== Using a Valid Domain

For security reasons, many Authenticators do not allow using localhost as the host for WebAuthn.
The WebAuthn specification requires that the RP ID is a valid, effective domain.
See https://github.com/w3c/webauthn/issues/1204[w3c/webauthn#1204] for details.

https://datatracker.ietf.org/doc/html/rfc2606#section-2[RFC2606 states] that .localhost is a valid TLD that is typically mapped to `127.0.0.1`.
This means that we can use example.localhost as our host name.

NOTE: If this does not resolve to 127.0.0.1, you can https://docs.rackspace.com/docs/modify-your-hosts-file[edit your hosts file] to map passkeys.localhost to 127.0.0.1.

+

./etc/hosts
----
127.0.1.1 example.localhost
----

=== mkcert

Use https://github.com/FiloSottile/mkcert[mkcert]

[source,bash]
----
mkcert example.localhost
----


This repository is exploring multifactor authentication with webauthn. To follow along on the discussions see https://github.com/spring-projects/spring-security/pull/6842

* Visit http://localhost:8080/
* Log in with user / password
* If you visit http://localhost:8080/ no additional authentication is required
* If you visit http://localhost:8080/secure you will be prompted for webauthn log in.
The first time you will be required to register.
* Use http://localhost:8080/logout to log out
Support is now Merged into Spring Security 6,4. See https://docs.spring.io/spring-security/reference/6.4/whats-new.html#_passkeys

0 comments on commit 64d74f9

Please sign in to comment.